Conventions for Writing Computer Instructions

These conventions are meant to help and guide you when you are writing computer instructions, for example when you are contributing a procedure to the Knowledge Base. Please refer to Chapter 4 of "Designing Readable Documents" for more information or an explanation of some of the conventions in this overview.
Of course, the other chapters of "Designing Readable Documents" talk about other issues that are important when you are writing instructions. For example: "Planning ahead: Think about your audience", "Writing clear sentences," and "Using graphics and tables."

These conventions have been posted to the web recently, so please send any comments, additions, or questions about them to IT Services Learning and Information Systems .

In this overview you will find quick guidelines and conventions for:

Step-by-step instructions
Commands, menu items, and buttons
Spelling of technical terms and menu items
Key names and sequences
Computer output
Asking for user input
Word choice: Use precise language to describe what you mean
Referring to other procedures

Step-by-step instructions

• Use a numbered list, and put steps of a step-by-step procedure in a logical order.
• Use parallel instructions for the list entries.
• Try to limit a step-by-step procedure to seven or fewer steps. If you have more steps, split the procedure in two parts and use subheadings.

  (More about lists, parallel constructions, and an exercise in creating sublists in chapter 4 of Designing Readable Documents.)

Example: From the File menu, click "Open".

• Put commands and menu items in bold when you use them in a procedure step.
• Use double quotation marks to indicate a command or a button instead of using the word "command" or "button."

Example: Click "OK"
Example: From the Insert menu, choose "File…".
• Place the period outside the quotation marks (unlike normal American spelling). This avoids confusion because what is in quotation marks is now exactly what is shown on the screen. Only place periods within the quotation marks when they are part of the command name.

• Write sentences to describe instructions instead of a list of commands.

• List instructions in the sequence that people will follow them.

(More about commands, buttons, and menu names in chapter 4 of Designing Readable Documents).

Spelling of technical terms and menu items

• Follow spelling and capitalization as presented in the interface of your computer.
• Do not capitalize generic names, such as toolbar, menu, and scroll bar, but do capitalize a specific name, as for example in: the Database toolbar.
• Use official spelling for technical terms and product names (check the box or the manual).
• Go to the IT Services Standard Glossary of Terms to find out what abbreviations stand for and how to spell technical words.

  (More information about spelling and spelling and grammar resources in chapter 4 of Designing Readable Documents.)

Key names and sequences

Contributors to the Knowledge Base, please note:
Because of the way that some browsers display and print the left (< ) and right ( >) angle brackets on a web page, you have to use an extra space between the brackets and the text in the brackets.
For example:
<ENTER> may not be interpreted and printed properly by some browser, but
< ENTER > will be displayed and printed fine.
You don't have to use this extra space when you are writing in print.

• Put key names in all caps and between left and right angle brackets.

• Use bold, all caps, and angle brackets for keys that have to be pressed.

• Use one set of angle brackets connected with plus signs for key combinations (short cut keys).

• Use multiple sets of angle brackets separated by commas for key sequences.

(More examples of key names, key combinations and sequences in chapter 4 of Designing Readable Documents).

• Use screen captures to show what the result of an action should be.
• If there is a lot of computer output, only display the last line of it.

• Use "type:" (notice the colon) to ask a user to type the information.
• Put user input in italics.

• Put things that the user should substitute by something of their own in boldface italics.

• Use lower case in examples. Only use capitalization for case-sensitive text.
• Avoid confusion over what a user should type. Usually, place user input on the next line. If necessary, explain what should be typed.

• Note that "Type: h" is different from "Press < H >". See below in the section on word choice.

  (More examples of user input in chapter 4 of Designing Readable Documents.)

• Type or press? Type: h versus Press < H >
  "Type" refers to a situation where a user has to provide input (that usually will appear on the screen).

"Press" refers to a situation where the user has to issue a command by pressing a specific key.

• Click, select, choose, or point to?
  In general, use choose or select when you refer to actions for either keyboard or mouse. Use click when you refer to specific mouse actions, and use point to if pointing to an object is enough (rather than clicking it).

• Enter or return?
  Use < ENTER > rather than < RETURN >unless you are writing a text specifically for Macs. If refer to the key on keypad should specify user what < ENTER > they need use.
• Avoid language that suggests that a computer "thinks" or "feels". Use neutral words.
• Avoid jargon, such as "machine" (for computer), or "hit" (for press).

• Use bold and italics.

  Example: For more information, see also How to access Universal Disk Space.