Guidelines: Writing Clear Instructions in One Stop Articles
Fast Five Guidelines:
- Use numbered lists and bullet points.
- Use complete sentences.
- Do not use the word, please.
- Only state the best way to complete the task without alternatives.
- List as few steps as possible to complete the task.
Top Ten Guidelines for How to Make OneStop Instructions Easier to Read:
1. Make sentences a command.
- Good: Copy the file that contains the table.
- Bad: You need the password. Go into the keychain.
2. State the purpose of the task before how to do the task.
- Good: To start a new document, click File > New > Document.
- Bad: Click File > New > Document to start a new document.
3. Give the reader the information they need for the task ahead of time.
Good: The following hardware and software are required.
Bad: Run the installation. When asked for the code, go to the text file.
4. Write in the order that the reader needs to follow.
- Good: In Microsoft Word, click File > New > Document.
- Bad: Click File > New > Document in Word.
5. Use consistent verb form.
- Good: Download the print driver. Click More, and then click Download.
- Bad: It can be downloaded by clicking More and then clicking Download file.
6. Do not use directional language such as above, below, or bottom left-hand corner.
- Good: Click Menu. Or: In the preceding diagram.
- Bad: Click the button with three lines. Or: In the picture above.
7. If the user must press Enter after a step, include that instruction as part of the step.
- Good: Click the search box, type headers, and then press Enter.
- Bad: 1) Click the search box and type headers. 2) Press Enter.
8. For an optional step, type “Optional:” as the first word without parentheses.
- Good: Optional: Enter a PIN code.
- Bad: (Optional) Enter a PIN code.
9. Do not include keyboard shortcuts.
- Good: Copy the command, and then paste it.
- Bad: Press Ctrl+C, and then press Ctrl+V.
10. Focus on what the command prompt does without using “run the following command.”
- Good: In Terminal, deploy iOS installation.
- Bad: In Terminal, deploy the installer by running the following command.
Please contact Debbie Dramstad, Web Accessibility, and Applications Specialist, for more information.