Learning how to write a user manual is an important skill in technical writing. If you have ever read a manual, you were probably looking for the answer to a question or a series of questions. Poorly written manuals offer confusing information that leaves users with more questions than answers.
Users want quick access to solutions on how to complete tasks. They want to complete the task at hand without the burden of extraneous information. When you learn how to write a user manual that provides clear instructions, you can turn frustrated users into happy users!
The guidelines below will help you to write clear and concise instructions that help users to complete tasks without interference from information that is not needed for the task at hand.
Use lists for instructions
Tasks consist of a series of individual steps that people follow in a specified order, so it makes sense that you should always use numbered lists for tasks. The numbered list helps the user to visualize the order of the steps in the task.
Compare the two instruction manual examples below that describe the same task.
The first example uses a list to describe the task. The list clearly shows the sequence of steps in the task.
To capture an image using the Windows 10 Snipping tool:
- Type Snipping Tool in the search box on the taskbar and then choose Snipping Tool. The Snipping Tool opens.
- Click the down arrow beside New to choose the shape of the capture window: free-form, rectangular, window, or full-screen snips.
- Select the part of the screen that you want to capture.
- Click the Save button to save the captured image.
The example below uses a paragraph to describe the same task. The paragraph doesn’t do a good job of clearly showing the individual steps in the task.
To capture an image using the Windows 10 Snipping Tool, type Snipping Tool in the search box on the taskbar. Select the Snipping Tool to open the app. To capture the screen with the Snipping Tool, select New. Click the down arrow beside the New button to choose the shape of the capture window: free-form, rectangular, window, or full-screen snips. After you create the snip, click the Save button to save the captured image.
Use a single action in each step
The steps in a procedure are easiest to understand when each step describes a single action. When you include more than one action in a step, the user might get confused, especially if the steps are complex.
There are a few circumstances where you might include two steps in a step. If the steps are closely joined, and they are simple, you can join the two steps into one step. The step in the example below contains two actions that are closely related, so you could choose to include both in one step.
Choose the file and click OK.
Start each step with an imperative
Start each step with an imperative, such as “Enter”, “Click”, “Select”, etc. When you start each step with an imperative, you are providing the user with clear cues on the required action for each step.
The example below starts each step with an imperative that describes the individual step.
- Double-click in the header. The header is highlighted for editing.
- Highlight the text you want to change and type the replacement text.
- Click Close Header and Footer in the ribbon after editing.
Ensure that the user does something in each step
You should avoid writing a system response as an individual step.
The incorrect example below includes a step in a procedure and a system response to the step. But in the second step, the user is not doing something.
- On the Project menu, choose Open Project.
- The Open dialog window displays.
Instead, you should write the system response in the same step that initiates the system response.
- On the Project menu, choose Open Project. The Open dialog window displays.
Use graphics when needed
Simple instructions may not require graphics. But without any visual cues, users may have trouble following the steps. Graphics can guide users through a task and help users to be sure that they are on the right track.
- Try to include “just enough” graphics without disturbing the steps in the task. Use graphics as needed to help the user understand a step in a task.
- Avoid including too many graphics since they can interrupt the flow of the content.
- Do not use graphics as decoration. Use graphics only to support the steps in the task.
- Add graphics immediately below the corresponding step in the task.
- Use screenshots when you need to point to a specific part of the interface.
In the example below, the graphic helps the user to visualize the task.
To change the page orientation in Word:
- Click the Layout tab.
- Click Orientation in the Page Setup group.
- Choose either Landscape or Portrait.
Test the instructions
Once you have written your instructions and carefully proofread the text, you might think your work is done. Right? Wrong! You should also test the instructions by asking testers to try and follow your instructions. You will likely be surprised when you try out the instructions on others.
You could conduct a full usability test, but even simple testing using the think-aloud protocol can give you valuable feedback. When you test instructions, you ask the tester to follow the steps in the instructions and think aloud as he/she is doing the task. Simple testing can help you to identify where users might run into difficulty.
If you don’t have access to any users for testing, you can also test the instructions yourself. After completing the instructions, set them aside for a day or two so you can look at them with a fresh eye. Then follow the steps in the instructions. While this isn’t ideal, it may help you to see where your instructions are missing important information.
If you would like to become a technical writer, you may want to consider registering for our Professional Technical Writing Course. It is an online course where you will learn how to write and revise instructions, technical reports, and software manuals (key technical writing documents).
