The Microsoft Writer's Style Guide
After much behind the scenes negotiating, I have at last managed to
obtain a copy of Microsoft's Style Guide for its writers. I reproduce
it below for the benefit of those wanting to pursue a writing career
for the software giant:
Suppose you want to describe technology 'X'; here's what you do.
- Breezy Title
- Introductory Paragraph. Begin with some anecdote or
story that can, with somewhat tortuous logic, be applied
to 'X'.
- Now it's time for some background material. Be sure to mention
how great 'X' is. If there's a competitor with a technological
equivalent to 'X', forget about the time last year when you disparaged
it. That was then; now 'X' is the best thing ever! Every program,
from games to financial apps, should be using 'X'! Claim that 'X' is
an Open Standard, even for such patently closed technologies as those
based on COM.
- Now describe your sample application which shows how easy it is
to use 'X'. Make sure that it's a trivial example, so that only the
easiest and most obvious subset of 'X' is demonstrated. You get bonus
points if the example somehow includes the name of family members or
your pet.
- Now it's time for your app's source code. Be sure to use 'X's C API,
even if your example is otherwise in C++. By no means should you bother
wrapping that C code into reusable object-oriented C++, as that
would just confuse everyone. Be sure that you include the boilerplate
code that every Windows app needs, as it helps pad out the article.
- As you describe your code, constantly reassure everyone that,
while some facets of 'X' look difficult, it's not really that hard.
After all, even you could figure it out. Remember, engineers are
reassured when their teachers appear to have only a tenuous grasp on the
subject they're trying to teach.
- Finally, list your name and credits. Contradict your above
"I'm-just-a-Joe-like-you" comments with some arrogant statement
about what a top-flight programmer you are.
Throughout your article, remember that the point of writing is to
entertain. Your audience is counting on you for chuckles, not boring
technical information. Under no circumstances should you divulge any
information not already available in the baseline SDK. Condescension,
not completeness, is your aim.
Don't ask me who I got this from; I don't want to get my Microsoft
friend in trouble. Just remember me when you use this material to
make your million bucks as a Famous Technical Author.
If there is such a thing.
Dave Townsend /
townsend@patriot.net /
13 Feb 01