Slashdot Mirror
Book Review: Microsoft Manual of Style
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.
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
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'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.
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.
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."
Clearly they have no idea what they are talking about if they do not make any mention of TeX. No discussion of bounding boxes or kerning? What sort of technical writers are not worried about overfull hboxes?
Palm trees and 8
. . . now expanded to include the English language.
Great, another meaning for Content Management System.
"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?
The review is for the recently published 4th edition: http://www.amazon.com/Microsoft-Manual-Style-Corporation/dp/0735648719
'Nuf said.
It's in my bookshelf, right next to Apple's Guide to Open Systems.
Table-ized A.I.
doesn't that have nothing to do with technical writing?
Also, stop putting your comment in the subject box.
For large sets, this will be our guide even unto death, for the LORD will work for each type of data it is applied to...
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.
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.
"I don't know, therefore Aliens" Wafflebox1
???
"You can purchase Microsoft Manual of Style from amazon.com."
My AC stalker: " I personally agree with your posts most of the time, but that won't keep me from modding you troll"
pronounI verbHope pronounThey verbDon't verbEncourage adjHungarian nounNotation!
not for this book but there windows app store plans are the Chicago way with the pay to play part.
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.
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.
Swedish plasma phys. PhD student; MSc EE; knows maths, programming, electronics; finance interest; seeks opportunities
this.
http://www.youtube.com/watch?v=YvX3laQlg14
If you can read this... 01110101 01110010 00100000 01100001 00100000 01100111 01100101 01100101 01101011
Seriously, when I read the phrase "Microsoft Manual of Style," All I see in my head is that scene from Raiders where that one Nazis face is melting...
An enigma, wrapped in a riddle, shrouded in bacon and cheese
- We have this "travelling salesman" problem.
- I see. Oh, I know! Let's call it "sales representative" instead.
Swedish plasma phys. PhD student; MSc EE; knows maths, programming, electronics; finance interest; seeks opportunities
The Third edition is available new for only $240.96. The fourth edition, reviewed here is available for $19.99. QC fail.
All your database are belong to U.S.
I'm the real AC
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! "
Jesus was all right but his disciples were thick and ordinary. -John Lennon
Is it only the electronic edition of amazon or are the tables in this book really that ugly? That's pretty disappointing when you've got a "style" guide in your hands.
Saying your screenname aloud is unpleasant to my ears. I can only conclude that you are a poor artist.
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 advice on professional writing doesn't seem like a very good idea. They'd probably be a good place for Fisher-Price to go to design a UI for devices aimed at children, however.
Technical writers don't pick the GUI colour scheme. Writing is a different skill than GUI design. I doubt there's a significant correlation between how good a GUI is and how good the technical writing is. Or between either of those and how good or bad an ad campaign is (they hire other people to make those in the first place).
Maybe you took one look at Windows XP and decided you wanted those guys to design your Fisher-Price jumping gym. That's somewhat plausible I guess. What's not plausible is somebody took one look at Windows XP and said "I'm going to get these guys to write the assembly instructions for my Fisher-Price jumping gym". And then confusing those guys with the guys who wrote Halo.
... 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 a consistent look, feel and consistency'' is utter bunk.
A question that was not addressed by this review, I think, is quite telling. What does this style guide have over and above such style guides as the venerable CMS (my preference) or other style guides (APA, MLA, the EU's Interinstitutional Style Guide, et cetera)?
...with that?
It's a shallow recitation of the table of contents with little details thrown in for a splash of color. It doesn't say why the book is good, nor where it is deficient. In fact, it reads too much like the worst of technical writing.
Simply reciting facts, or regurgitating screenshots without any real context behind them, is cheap writing that doesn't do much good for anybody. This review seems to be along the same lines.
This sentence from near the end of the review sums it up perfectly: "Many authors simply write in an ad-hoc manner." That's a perfect description of his own review. A review should tell a story. It should have connections between paragraphs. It should be written to engage the reader. It needs to have some sense of unity.
Sigh. Enough ranting for today.
Seems a bit of an oxymoron to mention M$ and style in the same breath...
Win2K was nice, win 7 was nice, XP was Fisher price but easily switched and XP X64 was built like a tank and again easy to skin. if you want to talk fugly though then lets talk metro, the half assed "Its a desktop, its a tablet, its half of one and half the other and neither really works!" which has to be the stupidest damned UI since MS Bob. I mean do you see Apple making iOS the new mac OSX? Nope they are working on making the APPS work on both because hey! That actually makes sense. I swear MSFT and so many of the other UI developers are stuck with the cargo cult mindset where they THINK they understand a thing but in reality they are just aping the most obvious layer which which just gives you a "kinda sorta but not really" half assed design. And can we find the fucknuts that came up with the bright idea that ALL OSes should be fucking cell phones and throw them under a bus, please?
The sad part is they have a couple of really good products they just don't have a fucking clue what to do with them. they should push back Windows 8 for another 2 years to give Windows 7 time to be adopted by businesses and they should go back to having the consumer and business desktop be two different things. no business is gonna want the social bling bling fucking trainwreck that is Metro as a business OS, they should spin off metro into an OS strictly for ARM and X86 tablets and phones and leave Windows for the desktop. But frankly win 7 is damned good, winPhone 7 is nice, they just don't have a single original thought on what to do with either. in a way it reminds me of the clusterfuck that was HP and WebOS, where you have this really nice thing but a company so lame they couldn't sell porn in a prison.
ACs don't waste your time replying, your posts are never seen by me.
That's hilarious!
That's daft.
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
Dealing with 'technical writing style' from a company well-known for exactly their excellent style and technical writing. Every one of their products comes with a readable, useful user manual and their online resources are even better! Bonus!
because that's really annoying too.
To have a right to do a thing is not at all the same as to be right in doing it
So your post is completely off-topic?
I have to stop reading after the first few paragraphs.
Is there a Microsoft Manual of Grammar available?
Carol vs. Ghost
some people just don't get it.
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
Kriston
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 almost like you need something more than sheer force and established momentum to succeed long term..
..Mullah or Pope, Preacher or Poet, who was it wrote: "Give any one species too much rope and they'll fuck it up"?
Sardaukar1986 all slashdot knows you're a trolling noob though.