Notes on Microsoft Manual of Technical writing

Microsoft Press provides corrections for books through the World Wide Web at

http://www.microsoft.com/learning/support/. http://www.microsoft.comlearning/support/search.asp.

What is the difference between command, function and option?

What is the difference between check box and combo box?

What is Control Panel?

What is the difference between Drop Down menu and Pop Menu and Shortcut Menu and Sub Menu? 

In Microsoft style manual, Compact Disk used to be written as ‘CD-ROM’ and now; it is mentioned as ‘CD’. Even world’s largest software corporation has changed its style in order to keep their documents easily comprehensible.

Simple Rules

• Use Click for commands, command buttons, option buttons, and options in a list, gallery, or palette.

• Use Select and Clear for check boxes.

• Use Type or Select to refer to an item (as in a combo box) that the user can either type or select in the accompanying text box. You can use enter instead if there is no possibility of confusion

Except for the identifiers box, list, check box, and tab, the generic name of an item within a

dialog box (button, option, and so on) should not follow the item’s label, especially within

procedures..

Use bold type in procedures for dialog box titles, labels, and options.

Correct

To view bookmarks

1. On the Tools menu, click Options, and then click the View tab.

2. Select the Bookmarks check box.

Use lowercase for the name of the descriptor (“the Spaces check box”).

Introduction to Style Sheets

What is Stylesheet?

Style Sheet is not a set of rules but set of guidelines.

What is the advantage of Stylesheet?

Style Sheet helps the writers to maintain the consistency of style of writing by using a consistent set of terminology and style.

Who do design Style Sheets?

Style Sheets of a company are usually designed by experienced writers and editors.

Do Technical writers need to be aware of Style Sheets of different companies?

Various companies have got their own style sheets and it is advisable and useful for the Professional Writers to go through the style sheets of at least well established IT firms such as Microsoft, IBM, Oracle and Intel.

Boxes and Buttons

Check box: a square box that is selected or cleared to turn on or off an option.

Combo box: a text box with a list box attached and users can either type or select their choice.

Command button: a rectangular button that initiates an action. (e.g: OK button or Save button).

Drop Down button: Drop Down button is an arrow associated with a drop down combo or list box or some tool bar buttons, indicating a list the user can view by clicking the arrow.

Drop Down Combo Button: Drop Down Comb button is a closed version of a combo box with an arrow next to it.

Drop Down Combo Box: Drop Down Combo Box is a closed version of a combo box with an arrow next to it. Clicking the arrow opens the list. 

Drop-down list box: Drop Down List Box is a closed version of a list box with an arrow next to it. Clicking the arrow opens the list.

Group Box: Group Box is a frame or box that encloses a set of related options.

The group box is a visual device only.

List Box: A box containing a list of items the user can select. The user cannot type a selection in a list box.

Option Button: Option Button is a round button used to select one of a group of exclusive options.

Sliders (Track bar Controls): An indicator on a gauge. 

Spin Box is a Data Box with up and down arrows.

Text Box: Text Box is a rectangular box in which the user can type text.  The user can select the default text or delete it and type next text.

Menus and Options

Menus contain commands.

Dialog boxes contain command buttons and options.

Do not refer to a command as a menu item (except in content for software developers about the user interface), a choice, or an option.

• Refer to a command button simply as a button in content for general audiences.
• A Menu contains several Commands. When referring to a particular menu, use lower case for the word ‘menu’ in lower case letters.

             E.g.: Edit menu.

• Refer to a command button simply as a button in content for general audiences.
• When referring to a specific menu, use lowercase for the word “menu”, as in “the Edit menu.”
• Refer to unavailable commands and options as unavailable, not as dimmed, disabled, or grayed. However, in programming contexts, it is all right to refer to unavailable commands as disabled.  If you are describing the appearance of an unavailable command or option, use dimmed, but not grayed or disabled.
• Names of menus and menu commands are distinct elements on the screen. Do

             not combine the two names into one.

• In general, mention the name of the menu the first time you refer to a particular

             command. However, if the location of the command is clear from the immediate

             context (for example, a topic about the Edit menu), you may not need to                         mention the menu name.

Correct: On the File menu, click Open.

Incorrect:  Click File and Open.

Correct: In Control Panel, click the File menu, and then click Open.

• In content for home users and information workers, do not qualify the term menu with the adjective drop-down, pull-down, or pop-up unless the way the menu works needs to be emphasized as a feature of the product. Shortcut menu is acceptable, although in most cases you can avoid it. Do not use any of these terms as verbs. Avoid the words cascading, pull-down, drop-down, or pop-up to describe menus except in some programming documents.

However, in technical material, you might need to detail these specific kinds of menus to differentiate their programming constructions:

• Drop-down menu

• Pop-up menu

• Shortcut menu

• Submenu

Correct: Open the File menu.

Incorrect: Drop down the File menu.

Always surround menu names with the words the and menu.

Correct: On the File menu, click Open.

Incorrect: On File, click Open.

Correct: Click Open

Incorrect: Click on Open

• Do not surround command names with the words the and command.

However, in text, you can use “the … command” for clarity.

Correct: On the File menu, click Open.

Incorrect:  On the File menu, click the Open command.

• Never say “In the menu” but “On the menu”

Correct: On the File menu, click Open

Incorrect: In the File menu, click Open

• Do not use the possessive form of menu and command names.

Correct: The Open command on the File menu opens the file.

Incorrect: The File menu’s Open command opens the file.

• Follow the interface for capitalization, which usually will be title caps, and use

bold formatting. Do not capitalize the identifier such as menu or command.

Correct: On the File menu, click Open.

Incorrect: On the File Menu, click Open.

Control Panel: Control Panel contains icons that represent different Control Panel items.

• Do not use applets, programs, or control panels to refer to either the icons or the items.
• Use bold text for the names of the icons and items.

When referring to Control Panel itself, use roman type except when you are referring to the command on the Start menu.

• Do not use the when referring to Control Panel.
• Use bold text for the names of the icons and items.
• If you cannot avoid identifying Control Panel by a category, use the Control Panel application.  

• In procedures, do not surround command names with the words the and command.

In text, you can use “the ... command” for clarity.

Correct: On the File menu, click Open.

Incorrect: On the File menu, click the Open command.

Network Connections:

Referring to the mouse

• Avoid using the plural mice if you need to refer to more than one mouse, use

mouse devices.

Correct: mouse devices

Incorrect: mice/mouses

• Do not use cursor or mouse cursor to refer to the pointer. Use pointer or mouse

pointer instead.

1

Correct: pointer or mouse pointer

Incorrect: cursor or mouse cursor

Correct: right mouse button

Incorrect: mouse button 2 or secondary mouse button.

• The Microsoft mouse that includes a wheel and wheel button is the IntelliMouse pointing device. Always use IntelliMouse as an adjective, but do not use the IntelliMouse mouse.
• Use wheel button to refer to the third (middle) button on the IntelliMouse pointing device.
• Use rotate to refer to movement of the wheel itself.
• Use rotate, not roll, to refer to rotating the IntelliMouse wheel.
• Use mouse button to indicate the left mouse button. Use left mouse button only to teach beginning skills or in a discussion of more than one mouse button.
• Use right-click to mean “click with the right mouse button” after you have clarified the meaning.

Correct

You can click with the right mouse button (called right-click) to see a shortcut menu.

Correct: Hold down SHIFT and click the right mouse button.

Incorrect: SHIFT+click the right mouse button.

1

Correct: Point to

Incorrect: Move the mouse pointer to

(Note: The latter is acceptable only in teaching beginning skills)

Correct: Click

Incorrect: Click on.

• Use click with a file, command, or option name.

Use in to refer to clicking in a general area within a window or dialog box.

Correct: To see the Control menu, right-click anywhere in the window.

Click in the window to make it active.

Incorrect: To see the Control menu, right-click the window.

Always hyphenate double-click and right-click as verbs.

Correct: Double-click the Word icon.

Incorrect: Double Click the Word icon.

• Use press and hold the mouse button only to teach beginning skills.

• Use drag, not click and drag. Use press and drag only in entry-level products.

The drag action includes holding down a button while moving the mouse and then releasing the button.

• Use drag, not drag and drop, for the action of moving a document or folder.

It is all right to use drag-and-drop as an adjective, as in “moving the folder is a drag-and-drop operation.”

Correct

Drag the folder to the desktop.

Messages

Messages are of several types namely interactive message, warning message,

Interactive messages

An interactive message requires a response, such as clicking OK. For example, warning messages require the user to confirm an action before it is carried out.

There are three types of interactive messages, which are described in the following table.

1. Information:  Provides information about the results of a command. Offers the user no choice.

Example: Setup completed successfully.

2. Warning:  Informs the user about a situation that may require a decision.

Example: Do you want to save changes to Document 1?

3. Critical: Informs the user about a situation that requires intervention or correction before work can continue, such as a network being unavailable. Also used as the Stop Button in Microsoft Internet Explorer.

Example: The computer or share name could not be found. Make sure you typed it correctly and try again.

Note: Do not use the question mark symbol (?) to indicate a message that appears in the form of a question. Users may confuse it with the Help symbol.

Informative messages: Use present tense for informative messages.

Writing messages:

• Avoid “please.” It can be interpreted to mean that a required action is optional.

• Avoid uppercase text and exclamation points.

• Do not refer to implementation details that are invisible to the user. For example, do not refer to the names of functions or objects in the program.

• Avoid phrasing that will seem silly to the user, such as “unexpected error.”

• Avoid using placeholder variables in the middle of a message. They are very hard to localize.

For warning or critical messages, include an action the user can take to remedy the situation. If that is not possible, the message should include a Help button that links to a Help topic written especially for the message. For example, the following message includes the compiler string, which can be useful to product support staff. The additional information gives users a possible way to solve the problem.

Screen Terminology:  The following illustrations show a Windows desktop, an open window, a browser window, a Web page, and a document window, with the various elements that appear on them called out. The callouts use usual capitalization style for callouts, which is sentence-style capitalization.

Elements that appear in more than one illustration are not necessarily called out on each illustration. For example, the scroll bar and the Close button appear in all windows, so they are called out only in the illustration of an open window.

Property Sheets Vs Dialog Boxes

Dialog Boxes

Dialog boxes contain command buttons and other options through which users can carry out a particular command or task. For example, in the Save As dialog box, the user must indicate in which folder and under what name the document should be saved.

Toolboxes are simply dialog boxes with graphical options that are treated in the same way as other options.

Property Sheets

A property sheet is a dialog box that displays information about an object (the object’s properties). For example, the System Properties property sheet shows information regarding devices that are installed and how the system is performing.

Property sheets have command buttons. When properties can be edited, property sheets can also contain options. Both dialog boxes and property sheets can have tabbed pages that group similar sets of options or properties.

In general, avoid using dialog box or property sheet as a descriptor. If you cannot avoid a descriptor, use dialog box for both property sheets and dialog boxes unless your project style sheet provides different guidance.

The distinction may be important for software developers and information technology professionals, but do not distinguish in content for home users or information workers.

In content for software developers, buttons and other dialog box elements are called controls,

especially in discussions about creating them. Do not use control in content for home users

or information workers.

Note: In some hardware products, buttons, switches, and so on are called controls because they give the user control over various actions. For example, users use joystick controls to move around the screen, especially in action games. This usage is all right as long as the meaning is clear.

Dialog box elements

In most content, especially for home users and information workers, do not differentiate

between drop-down combo boxes, list boxes, and text boxes. Refer to such elements by

their label, and use a descriptor only if necessary for clarity. If you must use a descriptor,

use list or box. Do use the term check box, however.

Slider* (also called trackbar control in some developer content)

Spin box (do not use spinner or other labels): Text box with up and down arrows that the user clicks to move through a set of fixed values. The user can also type a valid value in the box. In the Date box, type or select the part of the date you want to change.

Tab* (also called tabbed page in technical documentation)

Labeled group of options used for many similar kinds of settings.

On the Tools menu, click Options, and then click the View tab. (Note: Always include tab with the label name.)

Text box: Rectangular box in which the user can type text. If the box already contains text, the user can select that default text or delete it and type new text.

In the Size box, select 10 or type a new font size.

Unfold Button: Command button with two “greater than” signs (>>) that enlarges a secondary window to reveal more options or information.

Unnamed Buttons: If you refer to unnamed buttons that appear in the interface, use the syntax given in the example and insert a bitmap showing the button, if possible.

Correct:

Click the Minimize button.

Most buttons are named in ToolTips, so if it is impossible to use inline graphics, use the

name only.

When documenting an alternate path to Control Panel items, use To open [name of item], with the name of the item in bold type.

When referring to Control Panel itself, use roman type except when you are referring to

the command on the Start menu. In that case, use bold type.

Do not use the when referring to Control Panel.

Correct: In Control Panel, open Network Connections.

To open Network Connections, click Start, click Control Panel, and then double-click

Network Connections.

MOUSE TERMINOLOGY

Referring to the mouse

• Avoid using the plural mice if you need to refer to more than one mouse, use

mouse devices.

Correct: mouse devices

Incorrect: mice/mouses

• Do not use cursor or mouse cursor to refer to the pointer. Use pointer or mouse

pointer instead.

1

Correct: pointer or mouse pointer

Incorrect: cursor or mouse cursor

Correct: right mouse button

Incorrect: mouse button 2 or secondary mouse button.

• The Microsoft mouse that includes a wheel and wheel button is the IntelliMouse pointing device. Always use IntelliMouse as an adjective, but do not use the IntelliMouse mouse.
• Use wheel button to refer to the third (middle) button on the IntelliMouse pointing device.
• Use rotate to refer to movement of the wheel itself.
• Use rotate, not roll, to refer to rotating the IntelliMouse wheel.
• Use mouse button to indicate the left mouse button. Use left mouse button only to teach beginning skills or in a discussion of more than one mouse button.
• Use right-click to mean “click with the right mouse button” after you have clarified the meaning.

Correct

You can click with the right mouse button (called right-click) to see a shortcut menu.

Correct: Hold down SHIFT and click the right mouse button.

Incorrect: SHIFT+click the right mouse button.

1

Correct: Point to

Incorrect: Move the mouse pointer to

(Note: The latter is acceptable only in teaching beginning skills)

Correct: Click

Incorrect: Click on.

• Use click with a file, command, or option name.

Use in to refer to clicking in a general area within a window or dialog box.

Correct: To see the Control menu, right-click anywhere in the window.

Click in the window to make it active.

Incorrect: To see the Control menu, right-click the window.

Always hyphenate double-click and right-click as verbs.

Correct: Double-click the Word icon.

Incorrect: Double Click the Word icon.

• Use press and hold the mouse button only to teach beginning skills.

• Use drag, not click and drag. Use press and drag only in entry-level products.

The drag action includes holding down a button while moving the mouse and then releasing the button.

• Use drag, not drag and drop, for the action of moving a document or folder.

It is all right to use drag-and-drop as an adjective, as in “moving the folder is a drag-and-drop operation.”

Correct: Drag the folder to the desktop.

• In general, use point to, not move the mouse pointer to. The latter is acceptable only

in teaching beginning skills.

Correct: Point to the window border.

• Use click, not click on.

Correct: Using the mouse, click the Minimize button.

• Use click with a file, command, or option name, as in click OK; but use in to refer

to clicking in a general area within a window or dialog box, not click the window or

click the Styles box.

Correct: To see the Control menu, right-click anywhere in the window.

Click in the window to make it active.

Incorrect: To see the Control menu, right-click the window.

Always hyphenate double-click and right-click as verbs.

Correct: Double-click the Word icon.

Right-click to see the shortcut menu.

• Use press and hold the mouse button only to teach beginning skills.

• Use drag, not click and drag. Use press and drag only in entry-level products. The

drag action includes holding down a button while moving the mouse and then

releasing the button.

• Use drag, not drag and drop, for the action of moving a document or folder. It is all

right to use drag-and-drop as an adjective, as in “moving the folder is a

drag-and-drop operation.”

Correct: Drag the folder to the desktop.

• Use rotate, not roll, to refer to rotating the IntelliMouse wheel.

Correct: Rotate the IntelliMouse wheel forward to scroll up in the document.

• In general, use mouse button to indicate the left mouse button. Use left mouse button

only to teach beginning skills or in a discussion of more than one mouse button,

when not referring to the left mouse button would create ambiguity.

• Use right-click to mean “click with the right mouse button” after you have clarified

the meaning.

Correct: You can click with the right mouse button (called right-click) to see a shortcut menu.

• When more than one mouse button is used within a procedure, identify only the

least commonly used button.

Correct: With the right mouse button, double-click the icon.

Documenting mouse procedures

• Be consistent in the way you list mouse procedures. For example, always list the

mouse method before listing the keyboard method if you document both.

• Do not combine keyboard and mouse actions as if they were keyboard shortcuts.

Correct: Hold down SHIFT and click the right mouse button.

Incorrect: SHIFT+click the right mouse button.

Writing messages:

When you write error messages, do not make the reader feel stupid or at fault, even if the problem is a result of user error. It is all right to use the passive voice to describe the error condition. It is all right to make third-person reference to the operating system or the program.

When you write messages, follow these guidelines:

• Avoid vague wording. Give specific names and locations of the objects involved.

• Avoid “please.” It can be interpreted to mean that a required action is optional.

• Avoid uppercase text and exclamation points.

• Do not refer to implementation details that are invisible to the user. For example,

do not refer to the names of functions or objects in the program.

• void phrasing that will seem silly to the user, such as “unexpected error.”

• Avoid using placeholder variables in the middle of a message. They are very hard

to localize.

Correct: The name of the object file conflicts with that of another program in the project.

Incorrect: You have named the object file with the name of another program in the project.

For warning or critical messages, include an action the user can take to remedy the situation. If that is not possible, the message should include a Help button that links to a Help topic written especially for the message. For example, the following message includes the compiler string, which can be useful to product support staff. The additional information gives users a possible way to solve the problem.

Key Names:

Correct

Arrow keys [Do not use direction keys, directional keys, or

movement keys.]

CTRL [not Control]

DOWN ARROW [Use “the” and “key” with the arrow keys except in key combinations or

key sequences. Always spell out. Do not use graphical arrows.]

ESC [Always use ESC, not ESCAPE or Escape.]

LEFT ARROW [Use “the” and “key” with the arrow keys except in key combinations or keysequences.]

RIGHT ARROW [Use “the” and “key” with the arrow keys except in key combinations or key sequences.]

SPACEBAR [Precede with “the” except in procedures, key combinations, or key sequences.]

TAB [Use “the” and “key” except in key combinations or key sequences.]

UP ARROW [Use “the” and “key” with the arrow keys except in key combinations or key

sequences.]

ALT

ALT GR

Application key [Microsoft Natural Keyboard only]

BACKSPACE

BREAK

CAPS LOCK

CLEAR

DELETE

END

ENTER

F1–F12

HOME

INSERT

NUM LOCK

PAGE DOWN

PAGE UP

PAUSE

PRINT SCREEN

RESET

SCROLL LOCK

SELECT

SHIFT

SYS RQ

Windows logo key

When telling a user to “type” a key, use lowercase bold, unless an uppercase letter is required.

Correct: Press Y.

Type y.

If the user must type the punctuation, use bold. If not, use roman.

Refer to the key only by its name—for example, “press F1.” You can use the and key with the key name if necessary for clarity—for example, “the F1 key.” For the arrow keys and the TAB key, list only the key name in key combinations without the and key.

Correct:

To move the insertion point, use the LEFT ARROW key.

To extend the selection, press SHIFT+LEFT ARROW.