We use instructions frequently, from using recipes to prepare meals to reading help systems to master software functionality. We don’t think of many of the “how-to” guides we encounter as instructions or technical writing — but they are.
To write effective instructions, you should follow these suggestions:
- Observe experts performing the procedure;
- Practice the procedure to be documented;
- Study your potential audiences;
- Prepare instructions in “chunks,” by task;
- Assume nothing about the end-user; and
- Test, revise, and retest your instruction drafts.
Base instructions on what a skilled expert would do to complete a procedure. Experts know what should be done and why. Take notes and ask questions when working with an expert. Ask your experts any questions you have and clarify any doubts you may have. You cannot write effective instructions if you don’t understand what you are writing about. Do not assume that you can infer reasons for various actions without asking.
Practice the Tasks
If you don’t know how something works, writing about it can lead to mistakes readers will notice. You don’t need to be an expert, and some tasks are best left to simulation, but you should have some level of personal connection to the instructions. It is a lot easier to try some tasks than others. Often, “close enough” is sufficient to recognize which questions a reader might have while using the instructions.
Some people tell us that a technical writer doesn’t need to know how a product works to write a good manual. This leads to some heated debates, but we believe people interested in and familiar with products write the best manuals. For us, the best examples of this are books on computer programming. Enthusiasm makes for better writing.
Who will be using these instructions? While it seems like a simple question, the answer can be quite complex. Consider how the experiences and skills vary between different users of computers. There is no single, unified “computer user” audience. Having multiple audiences is a common problem for authors of instructions.
Draft in Chunks
Most processes can be divided into smaller tasks or specific topics.
Breaking up complex instructions into organized chucks makes it easier
for readers to understand and follow the instructions. Writing and editing
these shorter sections is also easier.
For example, when baking a pie it is obvious that preparing the crust is separate from preparing particular fillings.
Never assume the user of your instructions knows special terms or some processes. It is difficult to think like someone without any knowledge of a task, but it is an essential skill when preparing instructions.
Test, Revise, and Retest
After you’ve written your instructions, find someone who represents your end user to test the clarity of the instructions. When your test subject is following the instructions, observe his or her behavior. Note any section of your instructions that confuse or frustrate your test subject.
After the test is finished, interview your test subject and ask him or her how easy or difficult they found the instructions, if there were any steps that were particularly confusing, and if there are any suggestions for improvements.
Knowing which steps are a challenge and which are easy helps a writer recognize what needs to be clarified. Using one or two volunteers to test the instructions will probably find most of the problems.
Challenges of Text
Writing “text-based” instructions is challenging.
- Headings and other cues help organize tasks;
- Tables clarify numeric data better than paragraphs;
- Bullet points and numbered lists guide readers.
The Power of Images
The old saying “a picture is worth a thousand words” is true for a reason: a well-designed graphic image is easier to understand than any written text.
- Visuals are more universal than text;
- Images can be more complete than text;
- Readers remember images better than text;
- Images are easy to compare to the actual task.
Some issues with images include:
- May not reproduce well, especially in black and white;
- Might require an artist or illustrator to create;
- Can use more space on the page, resulting in longer documents.