Microsoft Manual of Style

Reviewed by Scott DeLoach, published in Technical Communication, August 1998

 

ISBN: 0735617465 The Microsoft Manual of Style for Technical Publications provides over 300 pages of advice ranging from grammar, punctuation, and abbreviations to writing for translation, referencing Windows interface elements, and creating indexes. Also included is a handy list of acronyms, an index, and–best of all–HTML and WinHelp versions of the book and an HTML version of the excellent Microsoft Press Computer Dictionary. Overall, it’s an invaluable resource for anyone documenting Windows software.

To be honest, I was most excited about the online versions, so I explored them first. The WinHelp version is a pretty straight-forward single-source migration from the print document. It can be run directly from the CD without installing anything to your PC. Once open, WinHelp version uses the standard WinHelp 4.0 layout with Contents, Index, and Find tabs. Everything seemed to work as expected. The main window is pretty small, however, so you will probably need to maximize it. Conveniently, the "New topics and other changes" help topic links to the new topics, and the topics listed in "See also" sections are linked in the help file. A print button to print the revised topics would have been useful, but otherwise the WinHelp version is a great resource.

As might be expected, the  HTML Help versions are a little more difficult to use. The setup programs for both the dictionary and style guide will install IE 4.01, which is required, and place a shortcut to each book on the desktop. Of course, using the shortcut requires your to have the CD in your computer, but it is a little more convenient than copying the files to your hard drive. Strangely, the style guide’s shortcut says "Running Microsoft Office 97, Update Edition." I assume this title is a mistake. Once you get everything installed and working, the HTML Help style guide is nearly identical to the WinHelp version. The "New topics and other changes" help topic links to the new topics and the topics listed in "See also" sections are again linked to corresponding Help topics.

The HTML Help version of the Microsoft Press Computer Dictionary is formatted slightly differently, and it is a little harder to use. The Table of Contents only includes letters (rather than topics), so you must either scroll down to the desired topic or use the Index or Search tabs. However, the dictionary includes instructions on how to use HTML Help and an image of the book’s cover–a nice touch. The biggest difference between the two books is that the dictionary is supported by a website, where you can find corrections and updates. Hopefully, Microsoft will add a website for the style guide as well.

About eighteen new topics were either added or heavily revised for the second edition. Not much of a revision, but the new online versions and the inclusion of the HTML-based Microsoft Press Computer Dictionary make purchasing the new edition a reasonable investment. A list of jargon, slang, and Macintosh terms are supposedly provided in the book’s index, but I was unable to find them. However, they are provided in the online versions.

A One-Stop Reference

If you have a style question, chances are Microsoft has a guideline: there is a real wealth of useful information to be found between the covers. The entries for "bias-free communication" and "accessible documentation" discuss how to avoid stereotypes and how to design web pages, online Help, and print documents for people with various kinds of disabilities. The entry for "copyright pages and copyright screens" not only provides a good overview of copyright symbols, it also explains what copyright information should appear on a program’s copyright screen, a web page, and in printed documentation.

Three of the most useful topics are "dialog boxes and property sheets", "document conventions", "and "screen terminology." These topics define all of the common Windows screen elements with program and usage examples. Some of these decisions, such as whether a menu should be boldface, are controversial–more on that later–but it is extremely useful to have everything spelled out in a few pages. Photocopies of these topics make a great cube wall quick reference. The "procedures" topic explains how to write procedural topics, including how to handle syntax, single-step procedures, branching, access methods, and supplemental information. The "keyword and online index entries" topic addresses how to create an online index, from selecting terms to creating cross-references. My favorite topic was "Readme files and release notes," with an extremely useful explanation of what information to include in a readme file, the difference between a readme file and a release note, and a sample readme file.

"Click this!"

Style guides are always controversial, and the Microsoft Manual of Style for Technical Publications is no exception. As the authors state in the Introduction, "this guide is to help Microsoft [emphasis added] writers and editors maintain consistency within and across products. It is not a set of rules." The purpose of the book is to offer guidelines and advice, not unbreakable rules–unless you work for Microsoft. Otherwise, it is your responsibility to decide which guidelines to follow and which to revise. Even Microsoft’s technical writers don’t always follow the guidelines. For example, take the title of the book: Microsoft Manual of Style for Technical Publications. The entry for "manual" states, manual "sounds old-fashioned and is not user-friendly" and the title is a little formal. Based on the entry "Titles of Books," a better title might be Microsoft Technical Publications Style Guide.

The best way to use the book is to review the guidelines and apply them as you see fit. About two years ago, I worked on a team that adopted as our style guide the first edition of this book. We bought a copy for everyone on the team and held weekly meetings to discuss the guidelines. Based on those sometimes heated meetings and a page-by-page review of the current edition, I made a list of ten guidelines that seem worth discussing before adopting:

entry

Microsoft says…

…not…

check box

Select the Spaces check box.

Check the Spaces check box.

click

On the file menu, click Open.

From the File Menu, select Open.

dimmed

If the option appears dimmed, it is unavailable.

If the option is shaded, it is unavailable.

ellipses

On the File Menu, click Print.

Select Print… from the File menu.

humor

Don’t use – it can confuse and it hard to translate.

 

i.e., e.g.

Don’t use. use "that" and "for example."

 

log on

Log on to the network.

Sign on to the network.

program

Use "program" for end-users, "application" for developers.

 

select

In the Size box, select 10.

Select 10 in the Size box.

second person

Now Windows is faster and easier to set up.

We’ve made Windows faster and easier to set up.

Many of these guidelines were controversial because our team’s existing style guide and our own opinions differed from Microsoft’s recommendations. Unless you are a lone writer starting the first manual for a new company, you will probably face the same problem. Although our meetings could get a little stressful, I think you will get the best results by discussing where you want to make changes to the guidelines. Remember to consider not only word choice, but boldfacing and formatting issues. One of our biggest arguments revolved around whether we should boldface menus and menu commands.

Our end result was a WinHelp style guide based on the book, our modifications, and other project-specific and formatting information. By moving the information online, we were able to provide a single source for modifications and updates. And, the style guide served as an example of our team’s online help design and template.

"Need" vs. "Want"

With any purchase, a good question to ask is "Do I really need this?" As Microsoft helpfully points out, "Need connotes a requirement or obligation; want indicates that the user has a choice of actions." If you are documenting Windows software, you need this book. If you are documenting computer hardware or software for another operating system, you will probably want this book. Why? Most of the information is not specific to Windows and could be applied to any technical communication project. However, there are other style guides (Sun’s Read Me First! : A Style Guide for the Computer Industry, Wired’s Wired Style : Principles of English Usage in the Digital Age, and numerous web-specific style guides come to mind, including Hackos and Steven’s Standards for Online Communication and Horton’s Designing and Writing Online Documentation: Hypermedia for Self-Supporting Products) that might closer match your specific needs. Whichever book you choose, you will need to review the guidelines and apply them to fit your needs.

Comparatively, the Microsoft Manual of Style for Technical Publications holds up rather well. Sun’s style guide has good information on document templates that seems missing from the Microsoft book, and Sun includes FrameMaker document templates. Microsoft Word templates would be a great (and obvious) addition to Microsoft’s book–assuming they use Microsoft Word (I hope so!). However, the Microsoft style guide is more comprehensive and a little more approachable. Wired’s style guide is definitely unique, and people seem to love it or hate it (if you thought the Microsoftstyle guide was controversial….). To their credit, the authors of the Wired style guide do a great job of covering new terms, and they support their book with a website. Unfortunately, I don’t think I could make it through consensus meetings to adopt the Wired style guide for anything other than web sites. Hackos and Steven’s Standards for Online Communication and Horton’s Designing and Writing Online Documentation: Hypermedia for Self-Supporting Products provide great information about writing for online, but they do not provide the depth of the Microsoft style guide (nor is that their goal). If you are writing online Help, however, either would make a great partner to the Microsoft style guide. Other potential resources are IEEE Standard 1063, IEEE Standard for Software User Documentation and ISO/IED 12119:1994, Information Technology: Software packages, Quality Requirements and Testing. Although both are short (around 30 pages), they contain very useful information and recommendations that are backed by highly-respected standards organizations.

While browsing the Microsoft Manual of Style for Technical Publications, I was really interested in atypical topics such as "readme files and release notes" and "copyright information." In the Introduction, the authors mention that a project-specific style sheet should also be referenced and followed. However, many readers have never seen a project style sheet and have no idea what one looks like or how to create it. Ideally, I would like to see a separate Microsoft Guide to Creating Technical Documentation that would include these overview and procedural topics. For example, I would like to see sample project style sheets, sign off forms, and project time estimates. I would like to hear how Microsoft handles team documentation efforts, how they maintain, revise, and test documents. I would like an in-depth discussion of their documentation process.

The most valuable aspect of the Manual of Style for Technical Publications is simply being able to review Microsoft’s documentation guidelines. If you take the time to make your own decisions (and revise the online versions accordingly), you will greatly benefit from this style guide. Maybe for the next edition, Microsoft will use a three-ring binder and provide a Microsoft Word version to make modifying the print version easier, too.

Leave a comment

You can use these tags : <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>