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.
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.
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…'
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' (https://www.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:
- Use short headings.
- Where applicable, use bulleted lists. A bulleted list is easier to read than a paragraph of text.
- Write short paragraphs.
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:
- Devices have different screen sizes and readers can change the size of text. Therefore, writing text to fill only one screen is not practical, because the number of words that will appear on a screen is not known.
- Some topics are large and contain much information. Dividing a large topic into many smaller topics does not increase the clarity of the text. A topic can be too small. I have a large screen area. I do not want a set of small topics that only partly fill a screen, because I must click unnecessary links.
- A reader who does not scroll down to find information will probably not click a link to find information. I think that the problem is not whether a user must scroll or click a link. The problem is that the information is not clearly organized. The user does not know whether the information is available.
- Some people do not want to read large amounts of text from a screen. Therefore, they print the content. If content is in many short topics, possibly, much paper is wasted.
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 all 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://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:
- The Global English Style Guide, John R Kohl, 2008
- The Elements of International English Style, Edmond H. Weiss, 2005.
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:
- IBM recommends that a sentence has not more than 20 words.
- LEC recommends that a sentence has between 15 and 20 words.
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:
- A neutral colour is gray (https://en.wikipedia.org/wiki/Gray).
- A neutral colour is a colour that "does not attract attention" (http://wordnetweb.princeton.edu/perl/webwn?s=neutral-coloured).
- A neutral colour is "not very bright or strong, such as grey or light brown" (www.oxfordlearnersdictionaries.com/definition/english/neutral_1).
The section 'Web, software, and HTML issues' gives many useful technical guidelines. For example, you cannot be sure 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:
- Technical communicators cannot know about all the applicable laws in all countries. A large legal team that constantly reviews the laws of all countries is necessary. (A better location for the guideline is the next section, which is about possible legal problems.)
- To prevent people in a particular country from viewing a website or from downloading files from a website is not possible.
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 guideline is not sufficiently clear. Does 'many steps' mean 6 steps or 16 steps?
- Sometimes, the guideline is not practical. If a procedure requires 15 steps, then I cannot decrease the number of steps. (Possibly, I can make 2 procedures, but possibly, I cannot.) If a procedure that has 15 steps is a problem, then the designers must change the product such that a smaller number of steps are necessary to do the task.
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 (https://trace.umd.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 
RSS feed