Guidelines: Writing Clear Instructions
How to Make Instructions Easier to Read
Follow these principles to write clear, easy to understand steps that guide your reader directly to the task.
Use Command Sentences
Start each step with a verb to tell the reader exactly what to do.
-
Good: Copy the file that contains the table.
-
Bad: You need the password. Go into the keychain.
State Purpose Before Procedure
Tell the reader why they’re doing the step before how to do it.
-
Good: To start a new document, click File > New > Document.
-
Bad: Click File > New > Document to start a new document.
Give Needed Information Up Front
List any requirements before instruction steps, so readers aren’t stalled mid-task.
-
Good: The following hardware and software are required: USB barcode scanner, Driver version 2.3 or later.
-
Bad: Run the installation. When asked for the code, go to the text file.
Follow the Logical Order of the Task
Arrange steps in the exact sequence the reader must perform them.
-
Good: In Microsoft Word, click File > New > Document.
-
Bad: Click File > New > Document in Word.
Keep Verb Forms Consistent
Use active, present-tense verbs throughout.
-
Good: Download the print driver. Click More, and then click Download.
-
Bad: It can be downloaded by clicking More and then clicking Download file.
Avoid Directional Words
Replace “above,” “below,” or “left-hand corner” with clear labels or positional references.
Good: Click Menu. Or: In the preceding diagram.
Bad: Click the button with three lines. Or: In the picture above.
Combine Related Actions in One Step
Include “press Enter” or similar keystroke instructions as part of the same step.
Good: Click the search box, type headers, and then press Enter.
Bad: Click the search box and type headers. Press Enter.
Mark Optional Steps Clearly
Begin optional steps with “Optional:” (no parentheses).
-
Good: Optional: Enter a PIN code.
-
Bad: (Optional) Enter a PIN code.
Describe What Happens, Not How to “Run” Commands
Focus on the outcome of a terminal or command prompt action.
-
Good: In Terminal, deploy iOS installation.
-
Bad: In Terminal, deploy the installer by running the following command.
Omit Keyboard Shortcuts
Spell out actions instead of naming specific keys.
-
Good: Copy the command, and then paste it.
-
Bad: Press Ctrl+C, and then press Ctrl+V.
Formatting Tips
- Use numbered lists for sequential steps.
- Use bullet points for requirements or optional details.
- Use tables for comparing data only.
- Write complete sentences.
- Do not include alternative methods; show only the best way.
- Limit the number of steps to the minimum needed.