Re: Any comments on these 2 books?

[Jim Purcell <jimpur -at- MICROSOFT -dot- COM>]

Lisa Higgins wrote:

> I've never actually used the MS Manual of Style on the job, but that
> is by design. I was given it to look over and make recommendations
> on, and I found it absolutely appalling, and I very strongly
> recommend against using it.
>
Obligatory prefatory remark: I am speaking here for myself, and not for
Microsoft. I am not involved in the creation or marketing of the
Microsoft Manual of Style for Technical Publications (the MSTP). Buy it
or not, like it or not, use it or not. It's nothing to me. But c'mon,
now ....

If the criticisms outlined in this post are the worst of it, "appalling"
is rather an overstatement. You can find the style guide of a company in
your industry useful without agreeing with everything in it. Maybe some
things don't fit your situation exactly. Maybe you disagree with some of
the decisions its authors have made.  Maybe you just don't like the
company that published it. Unless you are under some employer mandate to
observe the guide in all its particulars, you are free to use what you
like and ignore what you don't. If you don't like "mouse devices," you
can say "mice." To do so does not make the style guide in question
useless. It just makes it not your style guide.

> Its publication followed fairly closely Bill Gates' statement that
> Microsoft was "not in the documentation business."
>
Lest we forget, only after-market publishers, contract technical
writers, and tech writing job shops are in the documentation business.

> And it shows. The manual seems to have been written primarily for the
> purpose of protecting their trademark of the term "Windows."
>
Trademark protection is hardly the primary purpose of the MSTP, as even
a cursory reading will demonstrate. Nevertheless, it is a perfectly
appropriate thing for a style guide to do. If a company does not protect
its trademarks, they will become generic terms. Any company big enough
to have a trademark and a lawyer will hammer this point endlessly to
everybody who writes anything. Why would a company not incorporate its
trademark lore in its style guide?

> The manual regularly recommends that single words be replaced with
> bizarre compound nouns and complex adjectival strings, and frankly,
> it doesn't really answer a lot of questions you'll probably have.
>
It's hard to respond to this criticism without some specific examples.
In any case, if enough people find these compounds too bizarre or these
adjectival strings too complex, the offending words will wither away
from disuse, style guide or no.

I'm not sure that the MSTP is intended to be exhaustive, but I imagine
that the authors would be interested in questions of general interest
that are going unanswered.

> I'd
> venture to say that a great deal of the success of third party
> documentation rests with corporate standards such as those now being
> made public in the MS Manual of Style.
>
Or maybe it's that after-market author do not have to write for whoever
might buy a product; they can tailor what they write to a specific
audience, whether they are writing "Windows NT for Dummies" or the
Windows NT Resource Kit. They can insert more personality in their
writing, because they are speaking for themselves, not for a
corporation. Their words are not construed as a legal representation by
the corporation as to the product's features and capabilities, so they
can base their writing on a mid- to late beta and get in one more
editing cycle.

> If I had a little more time
> today, I'd hone the edges on this conspiracy theory, but I don't, so
> I shan't.
>
Conspiracy theories explain so much, don't they? I don't know how
Microsoft intends to conquer the world by publishing a style guide that
undermines the work of its own tech writers, as Lisa alleges just above.
What I do know is that earlier editions of Microsoft's in-house style
guide circulated widely in samizdat. People documenting DOS- and
Windows-based products at other companies found a fourth-generation
photocopy of Microsoft's guide useful, not to mention easier than
developing a style guide of their own. If the MSTP is evidence of
anything, it's that Microsoft has found a way to make its style guide
pay.

Jim Purcell
jimpur -at- microsoft -dot- com
My opinions, not Microsoft's

 TECHWR-L (Technical Communication) List Information: To send a message
to 2500+ readers, e-mail to TECHWR-L -at- LISTSERV -dot- OKSTATE -dot- EDU -dot-  Send commands
   to LISTSERV -at- LISTSERV -dot- OKSTATE -dot- EDU (e.g. HELP or SIGNOFF TECHWR-L).
  Search the archives at http://www.documentation.com/  or search and
browse the archives at http://listserv.okstate.edu/archives/techwr-l.html