Book Review: Microsoft Manual of Style 110
benrothke writes "The Chicago Manual of Style (CMS), now in its 16th edition, is the de facto style guide for American writers. It deals with aspects of editorial practice, grammar, usage, document preparation and more. It's just one of many style guides for writers. The Microsoft Manual of Style, just released in its 4th edition, attempts to do for the technical writers what the CMS has done for journalists and other writers." Read below for the rest of Ben's review.
A style guide or style manual is a set of standards for the writing and design of documents, either for general use or for a specific publication, organization or field. The implementation of a style guide provides uniformity in style and formatting of a document. There are hundreds of different style guides available — from the The Elements of Style by Strunk and White, to the Associated Press Stylebook and Briefing on Media Law and many more. | Microsoft Manual of Style | |
| author | Microsoft Corporation |
| pages | 464 |
| publisher | Microsoft Press; |
| rating | 10/10 |
| reviewer | Ben Rothke |
| ISBN | 978-0735648715 |
| summary | Invaluable guide to becoming a better technical writer |
Microsoft's goal in creating this style manual is about standardizing, clarifying and simplifying the creation of content by providing the latest usage guidelines that apply across the genres of technical communications. The manual has over 1,000 items, so that each author does not have to make the same 1,000 decisions.
Anyone who has read Microsoft documentation knows it has a consistent look, feel and consistency; be it a manual for Visual C#, Forefront or Excel. With that, the Microsoft Manual of Style is an invaluable guide to anyone who wants to better the documentation they write.
For example, many writers incorrectly use words such as less, fewer, and under as synonymous terms. The manual notes that one should use less to refer to a mass amount, value or degree; fewer to refer to a countable measure of items, and not to use under to refer to a quantity or number.
Style guides by their very nature of highly subjective and no one is forced to take accept the Microsoft style as dogma. The authors themselves (note that the book was authored by a group of senior editors and content managers at Microsoft, not a single individual) note that they don't presume to say that the Microsoft way is the only way to write. Rather it is the guidance that they follow and are sharing it with the hope that the decisions they have made for their content professionals will help others promote consistency, clarity and accuracy. With that, they certainly have achieved that goal.
The book is made up of two parts; with part 1 comprised of 11 chapters on general topics.
Chapter 1 is about Microsoft style and voice and has basic suggestions around consistency, precision, sentence structure and more. The chapter also has interesting suggestions on writing bias-free text. It notes that writers should do their best to eliminate bias and to depict diverse individuals from all walks of life in their documentation. It's suggested to avoid terms that may show bias with regards to gender, race, culture, ability, age and more. Some examples are to avoid terms such as chairman, salesman and manpower; and use instead moderator, sales representative or workforce.
The manual also notes that writers should attempt not to stereotype people with disabilities with negative connotations. It suggests that documentation should positively portray people with disabilities. It emphasizes that documentation should not equate people with their disability and to use terms that refer to physical disabilities as nouns, rather than adjectives.
The book takes on a global focus and notes that since Microsoft sells its products and services worldwide, content must be suitable for a worldwide audience. For those writing for a global audience, those sections of the manual should be duly considered.
The manual also cautions authors to avoid too many technical terms and jargon. The danger of inappropriate use of technical terms is that people who don't think of themselves as computer professionals consider technical terms to be a major stumbling block to understanding. The manual suggests whenever possible, to use common English words to get the point across, rather than technical one.
The book provides thousands of suggestions on how to write better documentation, including:
do not use hand signs in documentation — nearly every hand sign is offensive somewhere
do not refer to seasons unless you have no other choice – since summer in the northern hemisphere is winter in the southern hemisphere
spell out names of months – as 3/11/2012 can refer to March 11, 2012 in some places and November 3, 2012 in others
use titles, not honorifics, to describe words such as Mr. or Ms. – not all cultures have an equivalent to some that are common in the United States, such as Ms.
Chapter 6 is on procedures and technical content, and explains that consistent formatting of procedures and other technical content helps users find important information quickly and effectively. In the section on security, the style guide notes not to make statements that convey the impression or promise of absolute security. Instead, the writer should focus on technologies or features that help achieve security; and suggests to be careful when using words such as safe, private, secure, protect,and their synonyms or derivatives. It is best to use qualifiers such as helps or can help with these words.
As noted earlier, the style guide is simply a guide, not an absolute. In the book Eats, Shoots & Leaves: The Zero Tolerance Approach to Punctuation, author Lynne Truss write of terms that are grammatically incorrect, but so embedded into the language, that they are what she terms a lost cause. With that, the style guide has the pervasive use of the term all right, as opposed to alright.
According to dictionary.com, although alright is a common spelling in written dialogue and in other types of informal writing, all right is used in more formal, edited writing. My own preference is that alright is clearer and ultimately more concise. In this guide, I found that Microsoft's preference for all right to be distracting.
Differences aside, part 1 provides vital assistance to any writer that is interested in writing effective content that educates the reader in the clearest manner possible. The book is the collective experience of thousands of writers and their myriad sets of documentation. The book provides page after pages of unique information.
Part 2 is a usage dictionary that is a literal A-Z of technical terms, common words and phrases. The goal of the usage dictionary is to give the reader a predictable experience with the content and to ensure different writers usage a standard usage of the same term. Some interesting suggestions in the usage dictionary are:
access rights – an obsolete term. Use user rights
collaborator – do not use collaborator to describe a worker in a collaborative environment unless you have no other choice as it is a sensitive term in some countries. Specifically, being a collaborator in a third-world country can get one killed.
email – do not use as a verb. Use send instead.
master / slave – do not use as the terminology, although standard in the IT industry, may be insulting to some users. The manual notes that its use is prohibited in a US municipality.
press – differentiate between the terms press, type, enter, and use, and to use press, not depress, hit or strike when pressing a key on the keyboard
Some of the terms suggested are certainly Microsoft centric, such as:
blue screen – they suggest not to use blue screen, either as a noun or a verb to refer to an operating system failure. Use stop or stop error instead
IE – never abbreviate Internet Explorer; always use the full name
Say what you will about Microsoft, but any technical writer who is serious about being a better writer can learn a lot from the writers at Microsoft. Microsoft is serious and passionate about documentation and it is manifest in this style guide.
Microsoft has been criticized for their somewhat lukewarm embrace of open source. With the Microsoft Manual of Style, Microsoft is nearly freely sharing a huge amount of their intellectual capital. At $29 for the paperback and $10 for the Kindle edition, the manual has a windfall of valuable information at a bargain-basement of a price.
This guide is a comprehensive manual for the serious writer of technical documentation, be it a high school student or veteran author. In fact, to describe the guide as comprehensive may be an understatement, as it details nearly every facet of technical writing, including arcane verb uses.
Many authors simply write in an ad-hoc manner. This manual shows that effective writing is a discipline. The more disciplined the writer, the more consistent and better their output. Anyone that wants to be a better writer will undoubtedly find the Microsoft Manual of Style an exceptionally valuable resource.
Ben Rothke is the author of Computer Security: 20 Things Every Employee Should Know.
You can purchase Microsoft Manual of Style from amazon.com. Slashdot welcomes readers' book reviews -- to see your own review here, read the book review guidelines, then visit the submission page.
Re: (Score:2)
???
"You can purchase Microsoft Manual of Style from amazon.com."
Re: (Score:1)
not for this book but there windows app store plans are the Chicago way with the pay to play part.
Re: (Score:1)
I thought the Chicago way was more like: " They pull a knife, you pull a gun. He sends one of yours to the hospital, you send one of his to the morgue. *That's* the *Chicago* way! "
what's in a name? (Score:5, Funny)
MS may well have written more technical documentation than any other company ever, but when I see this book title, I think of things like "The Pompeii Manual of Architecture" or "The Hindenburg Guide of Dirigibles" or "The Atlantis Treatise on Waterfront Properties."
Re:what's in a name? (Score:5, Insightful)
Re:what's in a name? (Score:5, Insightful)
If only accuracy were also included in that list of accomplishments. A helpful table of translations would help this problem. For instance, "never" means "probably not in testing" and "always" means "until somebody actually uses it."
Re:what's in a name? (Score:4, Informative)
I concur. Just ask the wine developers about how complete and accurate MS documentation is. They are reverse engineering a whole lot just because the documentation sucks in a way.
Re: (Score:3)
i'd agree with you for the old msdn.. but the latest generation annoys me.. while all the same information is there, they lack the old tree based view so you can find other related items with ease.. right now you can find documentation for what you want but it is no longer useful for finding something you want to use but don't know if it exists/what it is called exactly.
Re: (Score:3)
It's still there. Switch to Classic reading mode - it's in the upper left, and may be obscured behind a gear-shaped icon, but it's there. The new modes are simpler and render better on mobile browsers, but the classis MSDN is still available for those who find it familiar and useful.
Re: (Score:2)
Gah... upper right. My bad, sorry. The gear icon is labeled "Preferences" on mouseover. Mind you, this advice only works for the real MSDN documentation / reference stuff, not the new "Dev Center" BS.
Re: (Score:2)
thank you - my god i don't know how i missed that.. I've been dealing with the new version for so long.. it just isn't something i go into a lot, but when i go into i really need it.. and to be able to walk the documentation like the classic style lets you, that is real value to me..
again, thanks,., i do not know how i missed that.
Re: (Score:2)
Microsoft's documentation is generally well organized, comprehensive, and the writing style is simple and concise; basically everything you'd want technical writing to be.
Microsoft's documentation is pretty good, yes, but publishing a book on it as the ideal example to follow (without any caveats) is a dis-service to the industry. It isn't until fairly recently that you couldn't find anything on MSDN without doing a Google search first.
And yes, it is nice that they mix knowledge base articles with forum posts in their search results now, but nothing beats the way I've seen Macromedia do it (now owned by Adobe) and that's to allow people to post comments directly at the botto
Re:what's in a name? (Score:4, Interesting)
There is a lot of bad documentation out there, so Microsoft's is probably above average, but I wouldn't call it good. At least the .Net documentation is a huge collection of example code fragments but contains very little text that actually explains what the methods do. Especially important details like how the method reacts when the input is invalid, the state is invalid, the operation fails etc are often missing. Or some hint about the underlying implementation, so you can get a feeling which methods have to do a lot of work and which will return quickly. You can't learn those things from a code example, they have to be documented explicitly.
Re: (Score:3, Insightful)
Microsoft's technical documentation is actually pretty amazing compared to other vendors
Microsoft's documentation is quite often piss poor. At times, as older versions of Windows have been deprecated, notes specific to those platforms have disappeared from MSDN as if nobody needs to write compatible software any longer. You search MSDN for a commonly named API or class, and you end up being shunted to a Windows CE or .Net article first, as if they were the most common platforms (maybe MS would like them to be). Trying to find information about security models, virtualization, and other feature
Re: (Score:2)
And that's the good stuff they keep behind the counter at MSDN. The actual locally-stored help files are generally worth fuck-all. I can't remember the last time the MS help file told me something that wasn't obvious by inspection - everything they write is clear, simple and utterly useless.
Not that linux is effectively much better - imagine you had a thinko and accidentally typed your encrypted volume password at the command prompt - now try to find how to delete (let alone secure delete) a specific entry
Re: (Score:1)
Re: (Score:3, Funny)
I don't care much about documentation, but if Microsoft released a manual for coding, then I would start worrying.
Re: (Score:3, Insightful)
Microsoft Press have all sorts of technical books out. Most are of a very high standard.
Re: (Score:1)
Re: (Score:1)
or
"The 1882 Home Buyers Guide: Krakatoa edition". (it blew up in 1883)
Re: (Score:1)
It makes me think of a three-way with Janet Reno and Margaret Thatcher.
Re: (Score:3)
Re:I do not see any mention of TeX (Score:5, Informative)
The CMOS and this are English style and usage guides for writers, not primarily a printing and layout guides. The CMOS is the industry standard, but it is too specific and has too many entries to be a quick reference. Most big companies have their own supplemental guide for "house style".
Re: (Score:3)
The CMOS is also not necessarily the best resource for technical writing. I haven't used it as a bible since the 14th edition, but in those days the CMOS simply had no concept of bullet points in text, for example. Eschewing bullet points is good advice for lots of types of writing, but for an instructional text on a highly technical topic they can be quite handy. CMOS also tends to be behind the curve on matters of styling technical jargon for technical audiences (preferring "e-mail" to "email," for exampl
Re: (Score:3)
Agreed. The Chicago Manual is the defacto standard for academic writing, but not necessarily standard for other types of writing.
Re: (Score:2)
I think MLA and APA styles are probably more common than Chicago. I'd bet not using a style guide is most prevalent.
Re: (Score:3)
The kind who do WYSIWY(t)YG in MS Word?
Re: (Score:3)
Technical writers know that page layout and writing are two different disciplines. They know that writers needn't worry about the fine details of page layout because that's been taken care of by the template designer.
Not that this stops people asking the tech writer to change the layout ("but almost half the page is empty! If you decreased paragraph spacing by 1pt, you could fit that large graphic on this page!").
No, when writing a 400-page manual you can't lay out every page manually. Well, you could, but
Embrace, Extend, Extinguish. . . (Score:4, Funny)
. . . now expanded to include the English language.
Re: (Score:2)
Embracing open source?! (Score:5, Interesting)
"Microsoft has been criticized for their somewhat lukewarm embrace of open source. With the Microsoft Manual of Style, Microsoft is nearly freely sharing a huge amount of their intellectual capital. At $29 for the paperback and $10 for the Kindle edition, the manual has a windfall of valuable information at a bargain-basement of a price. "
Is this Microsoft astroturfing or is the author really that clueless about what free means?
1. I can't modify and redistribute. So it's not free-as-in-rights
2. It's $29, so it's not free as in beer
In what way is this guide supposed to be upholding OSS values?
Re: (Score:1)
Re: (Score:2)
It's "nearly free" meaning they're not making money off of it. The price of buying it pays for the writing and publishing costs.
Re: (Score:2)
If they do not make money off it, the most likely try to soil something.
Re: (Score:3)
Microsoft is sharing an internal document that probably cost them a huge number of man-hours to produce, and they're selling it for a very reasonable price. In no way am I a Microsoft fan, but I think it's cool of them to make some pretty hard-won wisdom available outside their organization.
Re: (Score:1)
But to compare it with open source is really really bad and reaching. The whole, "Can't modify and redistribute" thing is the 900 pound gorilla here.
One of the most important things about open source is the right to modify and redistribute.
The whole thing reeks of non FOSS. A good example of old school vs new school. Look at the java documentation online a
Oxymoron (Score:3, Funny)
It has company (Score:1, Funny)
It's in my bookshelf, right next to Apple's Guide to Open Systems.
Re: (Score:1)
Relax, Dude, we're just having a little geekfun
One question (Score:2)
Does the book also tell how to get the users to RTFM?
The only thing rarer than a well-written manual is a person who actually reads it.
Re: (Score:2)
Well, that's kind of the whole point. Making manual text more consistent and easier to scan and parse makes the manual more readable, so it will be less daunting to newbies.
The MMoS also includes advice on how to style text in dialog boxes and online help to make them more legible and less frustrating to users.
DEC had great manuals (Score:5, Informative)
Their Big {Orange,Grey,Blue} Walls were paragons of thoroughness and clarity.
Best news was that since it's was all done on computer, their on-line help system had exactly the same text as the dead tree manuals.
Re: (Score:2)
Borland Pascal documentation was done the same way!
Oh Noes!!! (Score:5, Funny)
pronounI verbHope pronounThey verbDon't verbEncourage adjHungarian nounNotation!
Re: (Score:2)
There are two kinds of Hungarian Notation:
Good: centigradeDegrees
FAIL: integerDegrees
Re: (Score:3)
Either way, if you're storing your measurement of temperature as an integer... you've got bigger problems than what you name the variable.
(Yes, I know we don't always need decimal precision for temperature. This was meant as a snarky comment and nothing more.)
Microsoft's Style ... (Score:5, Interesting)
I always find Microsoft's documentation to be characterized consistently by two properties:
1. Tons of GUI screen shots. 20 pages of dead trees or dead electrons to convey a single paragraph's worth of actual information.
2. There is no universe outside of Microsoft. They can't acknowledge it even when they try. Example - Microsoft Exchange is notorious for violating the IMAP standard for RFC-822 message size. Microsoft's documentation actually acknowledges that Exchange does something different, but calls it a "clarification" of the standard. Right.
Re: (Score:2)
Tons of GUI screen shots.
Isn't that the nature of the beast? Documenting systems that rely heavily on GUIs is a real PITA. For example:
Unix doc: "To prevent others from accessing your file, execute: chmod go-rwx file "
WIndows doc: "Right click here, choose "Permissions" or whatever, go to the "Access" tab, enable the "frobnitz" checkbox..."
Aieeee!
Re: (Score:2)
It sounds to me that sk999 is complaining that they use too many screen shots for the amount of information. For instance, unless you're speaking to a really clueless/newbie crowd, you don't need to have a screenshot for every single step you take, just the ones where there's likely to be some confusion. Of course, though, it depends on the intended audience. If it's a book for Windows newbies, then yes, you probably do need a screen shot showing the start menu being clicked on. If it's a book for exper
Re: (Score:2)
Ah, could be. This might be a "Microsoft Universe" problem.
We sell software that has a Web interface, and we've had customers take a .BMP image of Internet Explorer, embed it in a Word document and attach the Word document to an email when they could have cut-and-pasted a 50-character error message from the Web interface. :(
Re: (Score:2)
1. Tons of GUI screen shots. 20 pages of dead trees or dead electrons to convey a single paragraph's worth of actual information.
Just think of the electrons!
From Latin ("de" + ablative of "factum") (Score:1)
The Chicago Manual of Style (CMS), now in its 16th edition, is the de facto style guide for American writers.
You see, it's not actually a style guide, only de facto so.
Re: (Score:2)
This is also only true for many American writers. Many others prefer the Associated Press Stylebook. The two differ on various points.
Re: (Score:2)
I see you think you know latin and thus assume you under stand "de facto". Just in case, you are confused on this point, let's see what Merriam-Webster says:
1. de facto
adv \di-fak-()t, d-, d-\
Definition of DE FACTO
1: in reality : actually
2. de facto
adj
Definition of DE FACTO
1: actual; especially : being such in effect though not formally recognized
2: exercising power as if legally constituted
3: resulting from economic or social factors rather than from laws or actions of the state
His usage looks good to
Re: (Score:2)
I'm afraid I don't follow you. The M-W definition is consistent with what I had in mind. Maybe I should explain what I meant, in case it was misunder stood.
Pro primo, let us establish that we agree on the following usage: "Our company has set no standard regarding what file format to write text documents in, but everyone has gravitated toward LaTeX, so it is the de facto standard." Pro secundo, I interpret my sentence about the CMS analogously, like so: "The CMS was never intended to be a style guide, but
Re: (Score:2)
That's not something you see every day.
Re: (Score:2)
Yay! I have no idea what "bitchfest" mean, though. That's totally like Greek to me. ;-)
Re: (Score:2)
I suppose I was confused by your sarcasm and the fact that there is not agreed upon style guide for American writers.
Reminds me of... (Score:2)
http://www.youtube.com/watch?v=YvX3laQlg14 [youtube.com]
Ark of the Covenant (Score:1)
Problems in computer science (Score:2)
- We have this "travelling salesman" problem.
- I see. Oh, I know! Let's call it "sales representative" instead.
At the Amazon link in the post (Score:1)
poor tables (Score:1)
I'm a huge fan of the The Chicago Manual (Score:2)
... nevertheless, the claim that CMS is ``the de facto style guide for American writers'' is overblown at best. In academia, I would be surprised if even a plurality of journals preferred CMS. The graduate school I'm attending prefers it but most journal articles I read certainly use other style guides.
Moreover, as someone who does technical support for a living and reads MSDN and TechNet quite a bit, I can tell you first hand that the claim that ``Anyone who has read Microsoft documentation knows it has
huh (Score:2)
That's hilarious!
That's daft.
TFR used what style guide? (Score:1)
Haven't read TFB and stopped reading TFR at this line:
"The book is made up of two parts; with part 1 comprised of 11 chapters on general topics. "
I wonder what is Microsoft's position on the use of the word 'comprise'
https://encrypted.google.com/search?q=how+to+use+the+word+%22comprise%22 [google.com]
Perhaps the reviewer should have read it (Score:2)
I have to stop reading after the first few paragraphs.
Is there a Microsoft Manual of Grammar available?
Wrong book linked on Amazon (Score:2)
If the OP meant to link to the 4th edition on Amazon whose Kindle counterpart is $10, then you should be linking to the 4th edition from 2012, which is ASIN: B0073U0UHI here:
http://www.amazon.com/Microsoft%C2%AE-Manual-of-Style-ebook/dp/B0073U0UHI [amazon.com]
Re: (Score:2)
doesn't that have nothing to do with technical writing?
Also, stop putting your comment in the subject box.
And don't change the comment subject line (Score:2)
Man, you're right about that, I hate that (Score:1)
Re: (Score:2, Informative)
Depends on what aesthetic you're aiming for. "Grishnakh" is a fine name for an evil orc who fights for the dark lord Sauron, and needs a name that evokes fear and dread in his enemies. If you want to design something fearsome-looking, then Grishnakh would probably be a good being to consult with, but probably not if you're trying to design cute children's toys.
MS, however, has frequently shown that their style is cheesy, even in their allegedly "Professional" operating system GUIs, so looking to them for
Re: (Score:2)
Re: (Score:1)
How do people on /. call you a Microsoft shill? At the risk of sounding sycophantic I don't always agree with your posts but they're always at least interesting and often quite insightful; quite the antithesis of shilling.
On-topic, I think the situation you describe must be very frustrating for Microsoft. They've proven time and again that as a one-trick pony their only tool is the brute force of their market hedgemony and their financial resources.
I take a small amount of satisfaction in that fact. It's al