A Summary and Topical Review of MMOS 4, 2012By 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.
ContentsItâ€™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-17Provides 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-32Includes helpful content on video content for the web, basic content testing, and community-provided content.
Chapter 3: Content for a worldwide audience, pp. 33-46Most 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-50This 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
Chapter 5: The user interface, pp. 51-98Natural 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
- icon names
- view names
- window names
Chapter 6: Procedures and technical content, pp. 99-130How 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.â€
â€œ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-176Capitalization, 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-188Words 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-420air 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.