Kathy Underwood
In the field of software documentation, Microsoft Manual of Style, Fourth Edition, is a watershed, especially in its effort to frame terminology and discourse vis-à-vis the natural user interface (that is, the new types of interfaces that have begun to appear, especially those that use contact gestures and air gestures).
Microsoft is putting its cards on the table: “This version of the Microsoft Manual of Style introduces the first wave of this new style (the natural user interface, NUI) and terminology with the intent to set some groundwork for future guidelines.”
In this edition, the authors include lots of talk of clouds, ribbons, and air gestures. But the greater part of the content has shifted substantially towards the user interface as the nexus of technology documentation. This information will be essential background as we consider changes to style conventions in the coming years.
The topical review that follows is intended to merely highlight notable changes, additions, and anomalies in MMOS. The review is organized by chapter titles. For the convenience of hard-copy readers, page numbers are included.
Contents
It’s a wee bit off. The “Forward” is supposed to be on p. xxii; it’s on p. xvii. The “Introduction” is supposed to be on p. xxiv; it’s on p. xix. Hey—it happens. Enjoy this moment of schadenfreude.
Chapter 1: Microsoft style and voice, pp. 3-17
Provides a set of documentation principles. For recommendations to aid in developing concise language, see the sections on “Precision,” “Language,” and “Sentence structure and grammatical choices.”
On contractions: “Use contractions to create a friendly, conversational tone.”
Chapter 2: Content for the Web, pp. 18-32
Includes helpful content on video content for the web, basic content testing, and community-provided content.
Chapter 3: Content for a worldwide audience, pp. 33-46
Most content in this chapter is very familiar to those who have read John Kohl’s Global English Style Guide (acknowledged as a resource on p. 46). But the chapter is still worth a read.
Global art, p. 40
Features a table with discussion on the careful choosing of colors; avoiding any kind of hand signs; and avoiding art based on English idioms.
MMOS recommends using alt text not only for people with disabilities, but also for worldwide users, users with different browsers, users who have turned off graphics, and users who might be using older technology.
MMOS especially recommends alt text for button images: “Users who do not understand the image can rely on alt text for an explanation. If you use art to label buttons, include text that describes the function of the button.”
Examples and scenarios, p. 41
The book also offers an excellent set of guidelines for use-case scenarios. It discusses how to avoid legally and culturally sensitive content. Here are a couple of examples of the recommendations:
“If you must mention real places, vary the locales that are represented from one example to the next. For example, you might mention Tokyo, Paris, and New York.”
“From example to example, vary the national identity of business and personal names, addresses, telephone numbers, email addresses, currency, and URLs.”
Legal issues with worldwide content, p. 45
“The use of names of people, places, and landmarks is restricted by law in some countries and regions. Do not name countries or regions, cities, or land features in disputed areas, and avoid showing them on maps. Errors in names or boundaries of disputed territory can be highly offensive in some countries or regions.”
References, p. 46
Windows User Experience Interaction Guidelines
: Massive catalog of UI guidelines per Microsoft.
Microsoft International Style Guides: Portal from which you can select an MMOS version by language.
Chapter 4: Accessible content, pp. 47-50
This chapter describes the Microsoft Accessibility Standards (MAS) requirements and gives additional references. Here are a couple of those:
- Microsoft Accessibility website: http://www.microsoft.com/enable/
- Accessibility info for developers: http://msdn.microsoft.com/en-us/windows/bb735024.aspx
- Trace Research and Development Center at the University of Wisconsin: http://trace.wisc.edu
The chapter also provides specific guidelines for accessible webpages, accessible writing, accessible graphics and design, and acceptable terminology.
Chapter 5: The user interface, pp. 51-98
Natural user interface (NUI), pp. xix, 51, 84-85, 341
The term for new types of interfaces that enable users to interact using their “voices, fingers, hands, and even their whole bodies.”
User interface elements: User interface syntax, pp. 59-60
The syntax section introduces the terms most commonly used to describe user interactions: click; select and clear; remove the checkmark; and type or select.
“Except for the identifiers box, list, check box, and tab, the generic name of a control (button, option, and so on) should not follow the label of a control, especially within procedures.”
Ribbons, menus, and toolbars, pp. 60-70
This table includes lots of graphics and definitions of UI elements.
Other user interface elements, pp. 78-82
This section describes controls that appear in dialog boxes and webpages. In MMOS 3 (p. 8-12), this section was referred to as “Dialog box elements.” The 4th edition still uses the four-column style, but the layout is much easier to read, the explanations are clearer, and the graphics are cleaner. This is the case, even though the font size in the MMOS 4 table is smaller than that in the MMOS 3 table.
Modes of interaction with the UI, p. 83 ff.
The book includes a new section on how to refer to gesture names (touchpads, games), air gestures, contact gestures (such as flick, tap, pan, and pinch), and so on. For related but slightly different perspectives, see iPad User Experience Guidelines or Blackberry Smartphones UI Guidelines.
High-level UI text checklist, p. 93
The book includes an eight-point checklist to use when reviewing UI text.
User-interface formatting, p. 95
MS really loves page measles, that is, bold formatting of individual terms in running text. I think this policy is a bit risky, given the proliferation of GUI “things with names” in tech doc: “In general, use bold formatting for user interface elements, both in procedures and in other text in instructional content.” Here are some items that the authors format in bold that are not generally bold in other text:
- dialog box names
- filenames
- icon names
- view names
- window names
Chapter 6: Procedures and technical content, pp. 99-130
How to write procedure steps
One of the suggestions for removing excess bulk from procedures: “You do not have to end a procedure with ‘click OK’ or ‘tap OK’ unless there is some possibility of confusion.”
Instruction style
“Avoid explicit descriptions of system responses.” p. 106
Cloud computing style and Cloud terminology, pp. 111-114
The book offers a very clear presentation of cloud terminology.
Table guidelines, p. 142 ff.
The table section is gratifyingly specific and sensible. Here’s an example: “It is all right to use lowercase for the first word in column entries if capitalization might cause confusion. An example is a column of keywords that must be lowercase.”
Chapter 7: Practical issues of style, pp. 131-176
Capitalization, p. 131
“Capitalize the second part of a hyphenated compound if it would be capitalized without the hyphen. Always capitalize the second part of a hyphenated compound if it is the last word of a heading or title.”
Downstyle capitalization, p. 132
Adobe has preferred downstyle since the company was called Aldus, and it is common practice in European languages. Microsoft has now joined in the practice; it is using sentence-style capitalization for titles and headings. Sentence-style capitalization is also easier for the worldwide audience to read and for machine translation to translate. For these reasons, Microsoft Manual of Style recommends “using sentence-style capitalization for titles and all headings, regardless of level.”
Subject-verb agreement, p. 179
The book offers a useful, Bryan-Garner-like (Garner’s Modern American Usage) discussion of subject-verb agreement. “Although using the plural they for a singular antecedent is gaining acceptance, it remains a problem for localizers and for non-native English speakers. Whenever possible, you should write around this problem.”…
“If you cannot write around the problem, do not alternate between masculine and feminine pronouns to refer to the same individual, and do not use he/she or s/he.”…
“It is all right to use he or she occasionally, but doing so excessively may distract the user. If you need to make third-person references to more than one person in the same topic, use he for some individuals and she for others. In all cases, leave no doubt about the antecedent for each pronoun.”
Chapter 8: Grammar, pp. 177-188
Words ending in –ing, p. 185
This entry uses the gerund meeting as an example of how you can get in trouble with –ing endings. To demonstrate the problem, MMOS asks us to consider the heading “Meeting requirements.” But then the ensuing discussion goes a bit askew:
“Note that meeting in this example heading can be a gerund . . . . It can also be a noun . . .”
But a gerund is a noun—albeit a noun with verbal intent. Gerunds are always nouns by definition. They aren’t nouns sometimes and adjectives sometimes. What’s not mentioned is that the word meeting in the heading can also be read as an adjective, in which case it would be a present participle. Present participles are more versatile than gerunds—they can be used with forms of the verb be and as modifiers of nouns and pronouns. But MMOS doesn’t mention the present participle till 10 pages later in the hyphenation section.
Hyphenating phrases with open compounds, p. 197
A closed compound consists of two or more words written together (such as longhouse or spokesperson). An open compound consists of two or more words written separately. Examples of open compounds are “post office” and “school bus.” In a sentence diagram, you would probably put the two words together on the same line.
Here’s what MMOS recommends: “Use an en dash (–) instead of a hyphen in a compound adjective in which at least one of the elements is an open compound (such as Windows NT–based) or when two or more of the elements are made up of hyphenated compounds (a rare occurrence).”
Here are the MMOS examples:
- Some programs have dialog box–type options for frequently used operations.
- Windows 7–compatible products
Usage dictionary, pp. 235-420
air gesture, p. 83
“An air gesture can be a movement made by any part of a user’s body to give an instruction to the program via a sensor or camera, or a pose that the user makes in front of a sensor or camera to which an avatar will react.” Examples: “To speed through the intersection, perform the Boost gesture by quickly raising both arms above your head.”
appears, displays, p. 246
Microsoft style: If you try to exit the program without saving the file, a message appears.
Not Microsoft style: If you try to exit the program without saving the file, a message displays.
choose, p. 264
“Use choose when the user must make a decision, as opposed to selecting an item from a list to carry out a decision already made.”
“Do not use choose as an alternative to click or double-click.”
click, p. 265
“It is all right to omit “Click OK” at the end of a procedure if it is clear that the user must click OK to complete the procedure.”
cloud, p. 266 (and Ch. 6, “Cloud computing style”)
“Use cloud as an adjective. Cloud may be used sparingly as a noun in content for a technical audience or in informal contexts.”
context menu, p. 270
“Do not use context menu or right-click menu to refer to the menu that appears when a user clicks the right mouse button in certain areas (or “contexts”), such as in a toolbar region. If you must refer to this menu by name, use shortcut menu instead.”
“In procedures, use shortcut menu only if doing so would help the customer locate the item in the user interface.”
“It is all right to use context menu in content for software developers, but make clear that it refers to the shortcut menu. See also pop-up.”
flick, p. 295
“Use to refer to the contact gesture of quickly moving one or more fingers to skip through content on the screen.” Examples: 1) “To move the picture to the right, flick it.” 2) “Flick through your contacts.”
Internet, intranet, extranet, p. 317
Always capitalize Internet.
pan, p. 351
A contact gesture. “Use to refer to moving the screen in multiple directions at a control rate.” Example: “Use your finger to pan across the map.”
path, p. 353
“The path usually specifies only a drive and any folders below the root directory. When a path also specifies a file, it is called a full path.”
simply, p. 382
“Do not use to mean that something is easy to do. It is generally unnecessary and can sound condescending if the user does not find the task as simple as you do. If you must have the meaning that simply conveys, use just instead.”
web, p. 410
What a relief to see this item. This non-capitalization should be a non-topic by now. The recommendation: “All uses of web as a modifier are lowercase except when following the user interface and in feature names such as Web Slice. Capitalize all words in the phrase World Wide Web, but the shortened form the web is lowercase.
- webpage, website, webcast, webmaster
- web-centric, web-based, web-enabled
- web address, web browser, web document
Microsoft Manual of Style, Fourth Edition: Your everyday guide to usage, terminology, and style for professional technical communications. 2012. Redmond, WA: Microsoft Press.