Microsoft Manual of Style: a review

Review by Mike Unwalla.

Elizabeth Whitmore (editor) and others, 2012. Microsoft Manual of Style, Fourth Edition. Redmond, US: Microsoft Press. 464 pages including index. ISBN 978-0-7356-4871-5.

I thank O'Reilly for giving me a copy of the Microsoft Manual of Style to review (http://shop.oreilly.com/product/0790145305770.do).

The Microsoft Manual of Style contains "best practices for writing content for the web, optimizing for accessibility, and communicating to a worldwide audience". I am specially interested in these guidelines, and I review the three applicable chapters after I discuss some general problems with the Microsoft Manual of Style.

The Microsoft Manual of Style can be better

The Microsoft Manual of Style is good, but Microsoft Press can make the book better. Sometimes, I struggled to understand the content because of typographic errors.

In the section 'Text for the web', the example bulleted list is not correct. Bullets are missing from the list items.

A bullet is missing from each list item.

The introduction to the Microsoft Manual of Style says, "Italic is used to call attention to word or phrases used as words rather than as a functional part of a sentence. For example: It is all right to use sync as an abbreviation…" But, some words that are in tables do not have the correct typography. For example, the section 'Names and contact information' shows a guideline about the internationalization of forms. Initially, I did not understand the guideline "Use title, not honorific, to describe words such as Mr. or Ms." I struggled for many minutes before I understood that the text means 'Use the word title, not the word honorific…'

The words 'title' and 'honorific' are not italic.

Sometimes, related content is in more than one chapter or section. The Microsoft Manual of Style has many cross-references, which is good. But, cross-references to section headings have no page numbers. For example, on page 36 in the chapter 'Content for a worldwide audience', there is a cross-reference to the section 'Words ending in -ing'. To find the section (page 185), I had to search the index and the table of contents, which wasted much time.

A good feature of the Microsoft Manual of Style is the related web page 'Errata for Microsoft Manual of Style' (http://oreilly.com/catalog/errata.csp?isbn=0790145305770). Readers can tell Microsoft Press about errors. All the comments are public.

Content for the web (chapter 2)

Websites are the primary method for communicating with users. Sometimes, a website is the only method for communicating with users. Therefore, a content strategy for websites is important to technical communicators.

To write effective content, a technical communicator must know things such as who will read the content, the objectives of the readers, how to measure success, and the budget for the project.

Frequently, users read text very quickly. Therefore, make sure that each word is important. In 'Text for the web', the Microsoft Manual of Style gives guidelines such as these:

The guidelines are good. However, except for links and text placement, I think that writing for websites is not different than writing for printed documents. All the guidelines are applicable to printed documents.

I do not fully agree with the guideline about text placement. "Content that is on the first screen ('above the fold') is more likely to be read—users are unlikely to scroll down to find more information. This means that you need to reduce word count (preferred) or increase the total number of pages (by dividing a page into shorter, separate topics.)"

Decreasing the number of words by removing unnecessary text is good. Short pages are good. However, to make topics fill only one page by increasing the number of pages is not always a good strategy:

Frequently, video is better than text for showing users how to operate a product. However, video is expensive to create and expensive to localize. Video is not good for complex procedures.

The guidelines for creating video are good. However, I did not understand one example.The Microsoft Manual of Style mentions a video that shows how to use a mouse. If someone cannot use a mouse, how does that person navigate to the content? To say that someone knows how to use a keyboard and a web browser, but does not know how to use a mouse is not logical.

Content for a worldwide audience (chapter 3)

"Writers and editors globalize content by creating content that is easy to read and translate. Content is localized by translating the content into other languages...".

In the Microsoft Manual of Style, the term globalization is a synonym for the term internationalization. Other experts use the term globalization to include both internationalization and localization. For example, see the Resource Directory and Editorial Index from Multilingual Computing Inc (https://www.multilingual.com/downloads/2012RD.pdf).

In this review, I use the terms internationalization and internationalize where the Microsoft Manual of Style uses globalization and globalize.

The advice in chapter 3 is good. Because the number of pages is restricted, the Microsoft Manual of Style cannot give all the possible guidelines. However, the 'Print resources' at the end of the chapter references two good sources of more detailed information:

Microsoft uses machine translation to make content available to a global audience. For machine translation, the Microsoft Manual of Style recommends that a sentence has not more than 25 words. Kohl and Muegge agree with the 25-word limit, but other experts recommend different numbers:

The Microsoft Manual of Style has all the usual guidelines that most style guides contain:

Internationalization is about more than only text. For example, the Microsoft Manual of Style discusses things such as graphics, examples, times, money, and contact information.

In the section 'Global art', one guideline is "Choose colours carefully… Neutral colours are usually all right." But, the Microsoft Manual of Style does not explain the term neutral colour, which has 3 or more meanings:

The section 'Web, software, and HTML issues' gives many useful technical guidelines. For example, do not assume that all users can access a fast internet service.

One guideline is, "Be aware of the restrictions for downloads in a country or region. Marketing statements, political statements, and names of people, places, and landmarks are restricted by law in some countries or regions. Restrict downloads that make reference to such information unless you are sure that the download is legal in the country or region." This guideline is not practical for 2 reasons:

Chapter 3 gives general guidelines about internationalization. If applicable for a particular term, the 'Usage Dictionary' gives more guidelines about internationalization.

Accessible content (chapter 4)

'Accessible content' gives basic guidelines about accessible websites, accessible writing, and accessible graphics. Accessibility is applicable to most people, not only people who have permanent disabilities. For example, some people use old technology.

One guideline about accessible writing is, "Minimize the number of steps in a procedure. Individuals who have cognitive impairments may have difficulty following procedures that have many steps." The guideline has 2 problems:

The chapter has only 4 pages, but there are references to good online resources. Because I did not know about the Trace Research and Development Center, I looked at the website and learnt new things about accessibility (http://trace.wisc.edu/).

The chapter is a good example of both minimalism and the combination of text and online content. Instead of repeating information that is available in other locations, tell people where to find the information.

See also

Articles about language

International English pages on the TechScribe website

Writing for people who do not read easily: workshop review

RSS feed