Microsoft Manual of Style for Technical Publications.
The Microsoft manual of style for technical publications provides over 300 pages of advice on subjects ranging from grammar, punctuation, and abbreviations to writing for translation, referencing Windows interlace 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 more interested in the online versions, so I explored them first. The WinHelp version is a pretty straightforward single-source migration from the print document. It can be mn directly from the CD-ROM without installing anything on your PC. Once open, the WinHelp version uses the standard WinHelp 4.0 layout with Contents, Index, and Find tabs. Everything seems to work as expected. The main window is rather small, however, so you will probably want to maximize it. Conveniently, the "New topics and other changes" help topic links to the new information contained in the manual, and the topics listed in "See also" sections are linked in the help file. A print button for printing the revised topics would be useful, but otherwise the WinHelp version is an excellent resource.
As might be expected, the two HTML Help documents are a little more difficult to use. The setup programs for both the dictionary and the style guide will install Internet Explorer 4.01, which is required, and place a shortcut to each book on the desktop. Of course, using the shortcut requires you to have the CD-ROM in your computer, but it is a little more convenient than copying the files to your hard drive. Strangely, the style guide's shortcut reads "Running Microsoft Office 97, Update Edition." I assume that 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 includes only letters (rather than topics), so you must either scroll down to the desired topic or use the Index or Search tab. 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 Web site, on which you can find corrections and updates. Hopefully, Microsoft will add a Web site for the style guide as well.
Approximately 18 new topics were either added or heavily revised for the second edition. This isn't 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 is supposedly provided, but I was unable to find them in the print version. However, they are provided in the online versions.
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," for example, 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, but also explains what copyright information should appear on a program's copyright screen, on a Web page, and in print documentation.
Three of the most useful topics are "dialog boxes and property sheets," "document conventions," and "screen terminology." These topics define all 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 quick reference posted on the wall near your desk.
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 is "readme files and release notes," which provides 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.
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 writers and editors maintain consistency within and across products. It is not a set of rules" (p. v, emphasis added). 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. I assume that the Microsoft editors preferred "manual of style" because it appears so frequently in titles in this genre.
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 the first edition of this book as our style guide. 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've made a list of ten guidelines that seem worth discussing before adopting. Here's what Microsoft recommends:
* check box - Write "Select the Spaces check box," not "Check the Spaces check box."
* click - Write "On the File Menu, click Open," not "From the File Menu, select Open."
* dimmed - Write "If the option appears dimmed, it is unavailable," not "If the option is shaded, it is unavailable."
* ellipses - Write "On the File Menu, click Print," not "Select Print . . . from the File Menu."
* humor - Don't use, because it can confuse and is difficult to translate.
* i.e., e.g. - Don't use; substitute that is and for example.
* log on - Write "Log on to the network," not "Sign on to the network."
* program - Use "program" for end-users, "application" for developers.
* select - Write "In the Size box, select 10," not "Select 10 in the Size box."
* first person - Write "Now Windows is faster and easier to set up," not "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 were sometimes 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 also formatting issues. One of our biggest arguments, in fact, revolved around whether we should boldface menu names 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. In addition, the style guide served as an example of our team's online help design and template.
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" (p. 185). 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 and numerous Web-specific style guides that might more closely match your needs. Whichever book you choose, you will need to review the guidelines and apply them to fit your needs. I'm thinking especially of the following:
* Sun Technical Publications' "Read me first! A style guide for the computer industry (Prentice Hall, 1996; reviewed in the November 1997 issue of Technical communication)
* Constance Hale's Wired style: Principles of English usage in the digital age (HardWired, 1996; reviewed in the August 1997 issue of Technical communication)
* JoAnn T. Hackos and Dawn M. Stevens's Standards for online communication (John Wiley & Sons, 1997; reviewed in the February 1998 issue of Technical communication)
* William Horton's Designing and writing online documentation: Hypermedia for self-supporting products (John Wiley & Sons, 1994; reviewed in the May 1996 issue of Technical communication)
Compared to these other works, 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 they do!). However, the Microsoft style guide is more comprehensive and a little more approachable. HardWired's style guide is definitely unique, and people seem to love it or hate it (if you think that the Microsoft style guide is controversial, have a look at this one!). To their credit, the editors of Wired style do a great job of covering new terms, and they support their book with a Web site. Unfortunately, I don't think that I could survive consensus meetings to adopt the HardWired style guide for anything other than Web sites. Hackos and Stevens's Standards for online communication and Horton's Designing and writing online documentation provide excellent information about writing for online presentation, 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 brief (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 created 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 and how they maintain, revise, and test documents. I would also like an in-depth discussion of their documentation process.
The most valuable aspect of the Manual of style for technical publications is simply our ability 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. Perhaps 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.
|Printer friendly Cite/link Email Feedback|
|Article Type:||Book Review|
|Date:||Feb 1, 1999|
|Previous Article:||The Art of Technical Documentation.|
|Next Article:||American Medical Association Manual of Style.|