Is the new Microsoft Manual of Style for you?

The 4th edition of the Microsoft Manual of Style (MMoS) has been updated substantially in a few crucial areas. It’s indispensable, if you work in a Microsoft domain and worth checking out if not.

Full disclosure: I’ve received a free review copy.

The previous edition of 2004 was becoming quite dated, so a new edition was eagerly awaited by many writers. Here’s what’s new, so you can make up your mind whether you need the new edition. I’ll focus on the first half, the “General Topics” with guidelines, which has the most significant updates.

General impressions

Guidelines have been reshuffled to emphasize the book’s shift from technical publications (such as online help or user manuals) to professional technical communications (which may also appear in web sites, blogs or wikis):

  • Previously, the first two chapters were dedicated to “Documenting the User Interface” with screens, dialogs, properties, etc. and to layout. So the message was: “Put proper words pretty on a page.”
  • Now it’s the “Microsoft style and voice”, followed by “Content for the Web”. So the new message is: “Know your audience and adapt your sound and your channel!”

Many guidelines and examples have been carried over or edited only slightly from the previous edition, which is fine, because they still apply.

Examples have adopted a new tone: Previously, they were marked as “Correct” or “Incorrect”, now they’re labelled “Microsoft style” or “Not Microsoft style”. Ironically, this modesty is undercut by another change in the text. Previous suggestions to “avoid” certain things have become more strict and now tell you “do not use”.

Layout feels fresher throughout and easier to read. See for yourself at amazon’s Look inside preview.

Cover of the Microsoft Manual of Style, 4th edition

The 4th edition by chapters

Ch. 1: Microsoft style and voice

A front-loaded new section presents 9 pages of “Principles of Microsoft style” along the lines of consistency, attitude, language, precision, sentence structure and grammatical choices, punctuation, contractions, and colloquialisms and idioms.

This is a welcome framework that can double as a declaration of values or truths to be held self-evident. A tech writing team I know uses the MMoS as the background for their in-house style guide – and with this new section, I guess they can get rid of some of the painfully argued standards and simply refer to this new edition.

I see this section not as a dictate by Microsoft, but as a modest proposal that’s worth considering – and discarding only with good reason. The book’s Look inside at amazon.com allows you to preview most of the chapter, so check it out to see what I’m talking about.

Ch. 2: Content for the web

This important chapter has also been rewritten and moved to the front where it has the prominent position it deserves. But to be honest, it trails several more focused, more expert works.

Still, this is now much more oriented towards useful content and starts with “Make the right content choices” and then goes on to advocate scannable, organized text with lots of links. Additional, but short sections address video, blogs, and wikis as well as task analysis, SEO and social media optimization.

So it’s now a decent attempt with helpful suggestions in the context of a style guide. If you’re at all serious about writing for an audience on the web, you will know or want some of the more expert titles.

Ch. 3: Content for a worldwide audience

This chapter has been edited and expanded, but not substantially changed from the previous chapter 3 “Global Content”. You can preview it, along with the new 2-column layout of guidelines and more information, as a sample chapter at Microsoft Press’ blog post.

Ch. 4: Accessible content

As the audience of technical communications has grown and diversified, accessibility has rightfully gained traction. So it’s a pity to see that this important topic still only gets 4 pages, and not much that’s new to boot.

This is little more than a first check list to make you aware of essential issues and remedies. You can find more in-depth information online.

Ch. 5: The user interface

This is the centerpiece of the manual – and essentially the law in what user interface stuff is called in the Microsoft universe. It’s where the new edition excels and the previous edition was most badly dated.

Much of this chapter had to be redone completely to include ribbons, smart phones, the MS Office 2010 “backstage view” (which is what the File menu section is now called that has replaced the application button). If you’re writing for any Microsoft product, including Windows, you will need this sooner or later.

Ch. 6: Procedures and technical content

This chapter has also been updated:

  • Cloud computing is in.
  • Guidelines for procedures, reference, XML and HTML  documentation remain.
  • Standards on documenting COM and ActiveX are out.

Ch. 7: Practical issues of style

This chapter now combines parts of what used to be chapters on “Content Formatting and Layout” and “Common Style Problems”. It contains essentially unchanged information about cross references, dates, numbers, page layout, titles & headings, etc.

Ch. 8: Grammar

A welcome addition to this chapter are several “international considerations”! If you’re writing for translation or an international audience, you’ll find these tips helpful, such as:

  • Avoid passive, because it translates poorly into some languages.
  • Avoid imperative in marketing tag lines which comes across as dictatorial in some cultures.
  • Avoid “(s)” for optional plural which translates poorly.

Ch. 9ff.

There have been few changes or updates to the remaining chapters on Punctuation, Indexes and keywords, and Acronyms and other abbreviations.

The verdict

The Microsoft Manual of Styles is a very helpful resource. It’s mainly well thought out and solves many problems, so you don’t have to.

If you write for Microsoft environments at all, you need this latest edition to stay consistent.

If you write for the web, accessibility, localization, international audiences, API/SDK documentation, you may need additional resources, either as online or print resources. The MMoS won’t – and in all fairness: can’t – deliver everything you need.

About these ads

14 Responses

  1. Thank you Kai for this detailed review, and thank you Microsoft for including chapters on Grammar, Punctuation, and Voice.

    Content for the internet is about so much more than content, as a few other resources widely disseminated and highly recommended on creating content for the internet suggest. Unfortunately, the writing of that content is a skill that is sadly neglected. I’m grateful to hear that Microsoft has considered it in the publication of this text, and I hope that its users will as well.

    • Thanks for your reply, corpwritingpro! It (and the MMoS) remind me how diversified our profession and skill set has become in recent years!

      I agree, writing well for the web is a rare skill. I, for one, wouldn’t claim to write for the web as well as I write for online help and user manuals. The MMoS is a good place to start – as long as you realize it’s not the be all and end all on those related topics.

  2. Hallo Kai
    Thanks so much for this very useful review. Our team is currently discussing the pros and cons of various style guides. I’ve shared a link to this post. :)
    Cheers
    Sarah

    • Thanks, Sarah, I hope the review can help you to make a suitable decision on whether to use or buy a style guide and which.

  3. Kai – Thanks for the review. What other resources do you recommend for web content style and international writing? I’m not finding as much as I expected, and your comments indicate that you have some preferences. :)

    • You’re welcome, Em, glad you’ve found it helpful!

      I’m afraid I have fewer recommendations than you might hope for. But two other books I swear by are:

      Mind you, both books are not style guides in a stricter sense and a little different from the Microsoft Manual of Style. But of course, you can check them out online before “committing” yourself to one of them. :-)

  4. Do you know if there is a MSTP that is for documenting for online help vs. documenting for pdf/print publication? The Web section seems to address writing web content, not specifically online help. Any thoughts? thx!

    • Hi, Sherry. Microsoft hasn’t even distinguished between online help and web writing in the previous edition of 2004 – and I can kind of see their point: I’m not sure I would understand or argue how online help writing should differ from writing on the web in general. Ginny Redish’s book “Writing for the Web” also largely avoids that distinction. So I think there’s a wider consensus that the distinction might not be all that helpful.

  5. […] when I happened upon a review of the new Microsoft Manual of Style for Technical Publications on Kai Weber’s Tech Writing Blog. It was an interesting review (you should go read it) so I thought I’d have a look at what […]

  6. Does the 4th edition cover Windows 8?

    • Hi, Tim. No, it doesn’t. Windows 8 is mentioned nowhere, and tiles are only mentioned in connection with Windows Phone. Hope this helps.

      • Thanks, Kai. (By the way, thanks too for your presentation at the STC conference.)

  7. I just read on LinkedIn that “e-mail” (in the 3rd edition) is now “email” in the 4th edition. Is that true? If so, that’s pretty big! :-) (I see that you still use “e-mail,” though.)

    • Indeed, Karla, “e-mail” in the 3rd edition of 2004 has now become “email” in the 4th edition. IMHO, it’s one of those cases that are mainly about consistency – but I don’t see that “e-mail” is any less clear or unambiguous than “email”.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

Follow

Get every new post delivered to your Inbox.

Join 741 other followers

%d bloggers like this: