Friday, February 24, 2012

Review: Microsoft Manual of Style, Fourth Edition

Author: Editors and Content Managers at Microsoft Corporation
Format: Paperback, 464 pages
Publisher: Microsoft Press; 4 edition (January 27, 2012)
ISBN-10: 0735648719
ISBN-13: 978-0735648715

I don't write technical content for Microsoft products very much these days (read: "practically never") but the Microsoft Manual of Style is not only considered required reading for those folks who do, but even for those of us who don't. Let me explain.

In many companies that produce technical documentation, there is a distinct set of rules that govern the voice, style, and other aspects in how the documentation is to be presented. Most people who aren't technical writers assume I just "wing it" whenever I create documentation for a technical product, but this is untrue. The documentation has to speak to a particular audience and for a variety of reasons, not the least of which is consistency, documentation for technical products must be presented in an exquisitely specific manner. Any technical style guide is designed to provide the writer with a template around which that presentation is organized.

Microsoft's fourth edition of their style guide is constructed into two broad areas: General Topics and Usage Dictionary. The first part is the narrative that addresses general subjects such as web content, the user interface, and even grammar and punctuation. The second part is the dictionary, but one that offers correct spelling and syntax around technical terms, from beep and bitmask to undo and update. Like any dictionary, you use it when you need to be sure you are using a technical term correctly or if you haven't the faintest idea on it's proper usage (and not all writers know how to spell all words, which is why we have dictionaries).

The first part of the book exists to familiarize the writer with the various aspects of writing style expected when documenting Microsoft products. It stands to reason that Microsoft's internal writing staff all use this book as the Bible; a Bible they themselves have produced. However, plenty of other companies must refer to Microsoft products in their documentation and it makes a great deal of sense to comply with Microsoft's preferred standards when doing so (just as we'd all wish Microsoft would write a version of Internet Explorer that complied with accepted web standards, but I digress).

As the front matter states though, no style guide can contain references to each and every aspect of each and every product, so there will be gaps. Several other references are suggested, both web resources and other guides and dictionaries. Together, this should provide the technical writer with a sufficient set of tools in order to create documentation that is readable by a general audience, internally consistent, and consistent with documents produced by other writers and agencies that comply with Microsoft writing standards.

This isn't a bad way to produce documentation for technical products that have nothing to do with Microsoft, either. Many technical writers work under temporary contract and provide writing services to a variety of companies needing documentation for general customers (such as end users) as well as technical consumers (such as IT staff). Smaller companies especially, won't have their own preferred style guide for their documentation, so it will be up to the writer to consult with the ops or dev team supervisor to agree upon a preferred style. While the Chicago Manual of Style is the accepted standard for professional writing, it is not designed specifically for technical documentation. In lieu of any other technical style, Microsoft's style guide is considered the de facto style by most businesses that need technical documentation.

I took a look at the Punctuation chapter in order to sample this book's wares, and was pleased that Microsoft indicated correct vs. incorrect styling as "Microsoft style" vs. "Not Microsoft style." There's more than one way to be right or wrong, but we're talking about Microsoft technical writing style, not general language usage, so what might be "right" in an email, could still be "Not Microsoft style".

You'll never memorize this book, so don't even try. If you are an aspiring technical writer, you don't want this stuck in your memory, anyway. That's why it's a reference and not undying prose. Plus, styles change over time, so you will need to continually adapt in order to stay current. That's also why you will need the current edition, rather than relying on previously published versions.

If you're worried about this guide stifling creativity, then you're in the wrong business. While there is certainly aspects of technical writing that require creativity, there is also a large amount of standards compliance required (and you thought programmers had all the fun). If you document Microsoft products or any other technical asset, assuming you want to write by some objective standard, a very good place to start is with the Microsoft Manual of Style.

2 comments:

  1. It's funny how often people who are aware of language make mistakes when writing (or talking) about it. I'm no exception. In this post you say "you haven't the faintest idea on it's proper usage". ... I think we know.

    ReplyDelete
    Replies
    1. Yeah. I goofed. I could have worded that better and obviously, I should have said, "...on its proper usage." Oy.

      Delete

Please make comments.