Instructions

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.

General Suggestions

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.

Observe Experts

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.

Audience Analysis

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.

Assume Nothing

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.