Follow Slashdot blog updates by subscribing to our blog RSS feed


Forgot your password?

Submission + - Book review: Microsoft Manual of Style

benrothke writes: "Untitled documentol{margin:0;padding:0}p{margin:0}.c7{max-width:468pt;background-color:#ffffff;padding:72pt 72pt 72pt 72pt}.c1{font-size:12pt;font-style:italic}.c3{text-align:justify;direction:ltr}.c0{color:inherit;text-decoration:inherit}.c5{color:#1155cc;text-decoration:underline}.c6{direction:ltr}.c8{height:11pt}.c4{margin-left:39pt}.c2{font-size:12pt}.title{padding-top:24pt;line-height:1.15;text-align:left;color:#000000;font-size:36pt;font-family:Arial;font-weight:bold;padding-bottom:6pt}.subtitle{padding-top:18pt;line-height:1.15;text-align:left;color:#666666;font-style:italic;font-size:24pt;font-family:Georgia;padding-bottom:4pt}body{color:#000000;font-size:11pt;font-family:Arial}h1{padding-top:24pt;line-height:1.15;text-align:left;color:#000000;font-size:18pt;font-family:Arial;font-weight:bold;padding-bottom:6pt}h2{padding-top:18pt;line-height:1.15;text-align:left;color:#000000;font-size:14pt;font-family:Arial;font-weight:bold;padding-bottom:4pt}h3{padding-top:14pt;line-height:1.15;text-align:left;color:#666666;font-size:12pt;font-family:Arial;font-weight:bold;padding-bottom:4pt}h4{padding-top:12pt;line-height:1.15;text-align:left;color:#666666;font-style:italic;font-size:11pt;font-family:Arial;padding-bottom:2pt}h5{padding-top:11pt;line-height:1.15;text-align:left;color:#666666;font-size:10pt;font-family:Arial;font-weight:bold;padding-bottom:2pt}h6{padding-top:10pt;line-height:1.15;text-align:left;color:#666666;font-style:italic;font-size:10pt;font-family:Arial;padding-bottom:2pt}

The Chicago Manual of Style(CMS), now in its 16th edition, is the de facto a 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.

A style guideor 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 EU Interinstitutional style guide, The Elements of Styleby Strunk and White, to the Associated Press Stylebook and Briefing on Media Lawand 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 Styleis an invaluable guide to anyone who wants to better the documentation they write.

For example, many writers incorrectly use words such as less, fewerand underas synonymous terms. The manual notes that one should use less to refer to a mass amount, value or degree; fewerto refer to a countable measure of items, and not to use underto 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, salesmanand manpower; and use instead moderator, sales representativeor 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 contentand 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 helpwith 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, 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 rightto 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 collaboratorto 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, enterand use,and to use press, not depress, hitor strikewhen 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 stopor stop errorinstead

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 comprehensivemay 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 Stylean exceptionally valuable resource.

Ben Rothkeis the author of Computer Security: 20 Things Every Employee Should Know."
This discussion was created for logged-in users only, but now has been archived. No new comments can be posted.

Book review: Microsoft Manual of Style

Comments Filter:

God doesn't play dice. -- Albert Einstein