Notes on Microsoft's "Manual of Style"

In classic default light gray

Microsoft's Manual of Style for Technical Publications, second edition (Microsoft Press, 1998) is self-described as "the standard reference for technical writers, editors, journalists, and others... this definitive reference is used throughout Microsoft and other companies for creating manuals, online help, Web publications, and much more." [1]

It will not surprise most of you that this tome is heavily Microsoft-centric, and some of the entries (shown later) are quite tendentious: they're encouraging you how to think. An electronic version is provided on the included CD; despite assurances that "Microsoft design guidelines ... allow the pages to be viewed successfully in most browsers," [2] the online material requires Explorer 4.0, which in turn requires Windows 95 or Windows NT with service pack 3.[3] Happy installing.

Anyway, let's get to the excerpts. I'll start with excerpts of interesting entries in the book, then list some terms I was surprised not to find.


Sample Entries from the "Manual of Style"

beep (n)
Use instead of alarm or tone to refer to a sound, as in "when you hear the beep."
Beeping is a DOSism. I'm dismayed computers are still doing it.
bookmark
... use favorite to refer to a bookmark in Microsoft Internet Explorer.

bug
Acceptable to use without definition or apology for a software or hardware error.
Quite seriously, wasn't "bug" deprecated in favor of "issue"?
code page
Do not use as a synonym for character set. A character set appears on a code page. For more information, see the Microsoft Press Computer Dictionary.
Code pages are a creaky old DOSism. Who uses them?
File Names and Extensions
... NOTE Do not use Foo, Fu, Foo.bar and the like as a placeholder for a file in Microsoft publications. Use a substitute such as Sample File or MySample instead.
Actually, they're right on this one; foo is for programmers. But file extensions are a creaky old DOSism.
font and font style
Use font, not typeface, for the name of a typeface design–for example, Times New Roman or Bookman...
I feel sorry for the print professionals who wish people would use the term font correctly. They won't win that battle with Microsoft on the other team.
First Person
Avoid the first person ... [n]ever use I except when writing a character such as Clippie ("Hi, I'm Clippie, and I'm your guide to Microsoft Office").
It's bad enough to be forced to use M$ Office. Seeing that winking paperclip is like getting a cream pie in the face while your 360-pound cellmate has a knife to your throat and is busy at your other end.
Fortran
Do not use FORTRAN (all uppercase) to refer to the programming language, and never spell out its origin of Formula Translation.
There seems to be more here than meets the eye... what's with that exhortation at the end?
gigabyte
One gigabyte is equal to 1,073,741,824 bytes, or 1,024 megabytes...
[usage example:] You will need to free 1 GB of hard disk space.
... to install Windows 98 with Internet Explorer 5.0.
greater, better
Do not use either term to designate system requirements or versions of a program. Use later instead...
[incorrect usage example:] You need a 486 or better processor.
Good advice. Many Microsoft products do not improve with age; for example, "Word 97 or better" includes Word 6, Emacs, BBEdit, and so on, and a "486 or better" processor is any chip that can divide properly and count to more than 64K.
hacker
Do not use hack in the sense of writing code or hacker to mean an amateur programmer. The words are slang. It may be appropriate to use hacker to refer to someone who illegally gains access to a computer system or network with the intent of causing damage.
I feel sorry for the Slashdotters, Linux people, GNU, and programmers in general who wish people would use the term hacker (vs. cracker) correctly. They won't win that battle with Microsoft on the other team.
Internet Explorer
Always use Microsoft Internet Explorer in first-level topic headings in Help, at first mention in a Web Page, and at first mention in a chapter. Then use Internet Explorer. Never use IE.
Can't ever find what you need in M$ online help? Try looking under 'M', for Microsoft. It's all stuffed there.
navigate
Avoid using the verb navigate to refer to moving from site to site, page to page... Instead, use explore to mean looking for sites or pages generally...
Blatant Microsoftism.
NT
Do not use; always use Windows NT. It's a Microsoft trademark.

plug-in
Although generically plug-in can refer to any small program that "plugs in" to another to add functionality, in Internet usage it almost always refer to a Netscape-specific component. Do not use as a synonym for add-in or add-on.

Entries that aren't in there, but should be

BSOD, Blue Screen of Death
Do not use; they're pejorative slang for Windows NT's propensity to crash. Use temporary suspension of service or stops responding.

C2 security
Use carefully; do not reveal that the workstation must be disconnected from the network to comply.

Bug fix
Use service pack instead. If you are charging the user more than $49, use Step-up or New Edition.

Doesn't scale up
Do not use; it's technical jargon. Use where do you want to go today or another marketing phrase.

Exploiter, Exploder
Do not use; they're pejorative slang. Use Microsoft Internet Explorer.

Micros~1
Do not use; it's pejorative slang, alluding to Microsoft's hacked-up way of handling long file names. Use Microsoft.

Micro$oft, M$
Do not use; they're pejorative slang, alluding to Microsoft's business practices or Bill Gates' venality. Use Microsoft.

Windoze
Do not use; it's pejorative slang. Use Microsoft Windows.

Plug and Pray
Do not use; it's pejorative slang referring to Windows 95's attempt to allow users to install some cheap clone peripheral in less than a weekend. Avoid this topic in general.

$Bill
Do not use; it's a Perl double-entendre. Use Bill Gates.


Notes

All citations are from the Manual of Style for Technical Publications, second edition.
1. Front and back cover blurb.
2. "HTML" entry, p. 116.
3. "About the Electronic Books", p. viii.

Want some more?

Hey, all you Microsoft-bashers are just jealous of success :P
For more mean-spirited M$ rants, see Teach Yourself HTM Programming.

Or see Kurumi's home page.