This topic will briefly describe things to consider when you are writing computer instructions. Usually instructions will consist of a step-by-step description of a specific task. First we’ll discuss some general suggestions for organizing such a procedure. Next, this topic will give specific tips on how to write the instructions and how to describe keys and menu items.

The suggestions in this topic are consistent with the way many people within IT Services write instructions. Additional tips were gathered from the Microsoft Manual of Style for Technical Publications (Second edition), published by Microsoft Press, Washington (1998). This manual of style is worth using when you write computer instructions.

In this topic:

• Organizing a procedure
• Conventions for writing about menus and commands
• Use precise words to describe what you mean
• Do not suggest that computers have emotions
• How to ask for user input
• Key names, combinations and sequences

Organizing a procedure

When you write a procedure, it is important to:

• Restrict yourself to information that is necessary for the user to carry out the action.
• Use a descriptive heading to forecast what is coming.
• Use numbered entries to describe individual steps, but use a bullet for a single-step procedure.

  EXAMPLE
  To use the full screen to display your document:

  • From the View menu, click "Full Screen".

• Use parallel constructions for the entries.
• Similar to a list, limit a procedure to seven or fewer steps. Instructional design experts say this is the maximum number of items people can remember at once. You may combine short steps if they occur in the same place (within one dialog box, for example), as illustrated below.

  EXAMPLE

  1. From the Tools menu, click "Options", and then click the "Edit" tab.
  2. …
     -or-

  1. From the Tools menu, click "Options".
  2. Click the Edit tab.
     
     

• Make sure it is clear what a user should type when user input is required. Try to format the text in such a way that the user input appears on a new line.
• Keep all steps of the procedure together. Try to keep all steps on one page in printed documentation, and keep a procedure to one screen if used online.

  Consider using a table when there are multiple ways to perform a task, depending on the choices the user would make. For example:

• Capitalize menu names, command and command button names, dialog box titles and tab names as you see them in the application interface.
• Do not capitalize interface elements used generically, such as toolbar, menu, scroll bar, and icon. Capitalize the names of functional elements that do not have a label in the interface, such as toolbars (the Database toolbar) and toolbar buttons (the Insert Table button).
• Make menu names bold when you use them in a procedure step.
• Put the options you choose from the menu in bold and in quotation marks.

  EXAMPLES

  • From the Help menu, choose "Microsoft on the Web".
  • From the Insert menu, click "Date and Time".
  • Select the "Automatically hyphenate document" check box.

Notice how the words "the" and "menu" are used with menu names, for example: "the Help menu". You can use "the Open command" in normal text; however don't use command names with the words "the" and "command," in a procedure, for example "the Paste command".

• Write sentences to describe the instructions, rather than a list of commands. In some cases though, you will use for example; Insert/Picture/Clip Art... because it is much shorter. Think about who you are writing for.
• Do not combine names of menu commands and menus into one name, because they are distinct elements on the screen. Also do not use the possessive form of menu and command names.

Put user input and program output in italics. You can use bold if you want to. Don’t capitalize it unless it is case-sensitive. Try to edit the text in such a way that you ask for user input on a new line.

EXAMPLE
Type: y
—or—
Type
Uniqueid@muohio.edu

In the last example, only 'uniqueID' is capitalized, to show that users should replace this word with their own uniqueID when they enter the information.

When telling a user to "press" a key, instead of typing the letter, format the key name in all caps.

EXAMPLE
Press < Y >

Key names, combinations and sequences

Key names
Capitalize key names and put them in brackets. For example: < ENTER >, < ALT >, < PRINT SCREEN >, < RIGHT ARROW >.

Key sequences
Use commas followed by spaces, as in < ALT >, < F >,
< D > to indicate a key sequence, the user should press and release < ALT >, and then < F >, and then < D >.

Short cut keys
Use a plus sign, as in < CTRL+V > to indicate key combinations for a shortcut key. Put all keys inside the brackets so the user knows it is one key action; the user has to press and hold down < CONTRO L> and then press < V >.

To show a key combination that includes a "shifted" key, such as the question mark, add < SHIFT > to the combination and give the name or symbol of the shifted key, such as < ? > or < $ >. Using the name of the unshifted key, such as < 4 > rather than < $ > could be confusing.

EXAMPLE
Poor: < CTRL+SHIFT+4 > or < CTRL+$ >
Good: < CTRL+SHIFT+$ >

Spell out the following special character names when you describe shortcut keys because these keys are difficult to see or can easily be confused with an action:

PLUS SIGN
MINUS SIGN
HYPHEN
PERIOD
COMMA