The Quick and Easy Guide to
Instructions and Procedures
Both instructions and procedures, sometimes called technical documentation,
describe a specific task in sequential steps. Usually, instructions are
written in the imperative or command voice, while procedures are written
in the neutral third person. Either way, the reader is looking for directions
on how to do something. A complete set of instructions and procedures is
called a document set. Often, this includes installation, operation
and troubleshooting documentation.
Writing Instructions and Procedures
Often, content is not the challenge in writing instructions. As the writer,
you may know the procedure or will usually be able to research the procedure
well enough to cover the required information. The challenge is to develop
a set of written instructions that is clear and easy for any reader to
use. There are some techniques that will help you write effective instructions:
Keep the language simple and direct. Remember to write in the active
voice, using imperative second-person (for instructions) or neutral third
person (for procedures). Avoid future tense and gender-specific language.
Use position titles when appropriate.
Always write to your audience's technical level. While keeping language
simple and direct, you should include expected technical language and acronyms.
You may need to consider multiple audiences.
Describe any necessary parts, tools or equipment before giving the directions.
This allows the reader to check his/her supplies before beginning the procedure.
List the steps sequentially. Using number lists (for ordered tasks)
or bulleted lists (for unordered tasks) helps the reader find and follow
the procedure. Begin with a line or lines of introduction for the tasks,
e.g. "To install the software, follow these steps:", followed by your list.
A vertical list is often easier to read than a horizontal list.
Emphasize tasks over results. Focus on what the user does, rather
than what happens after the action. You can still list the reactions, but
only after describing the user's tasks. One way to avoid confusion is to
include a decision table or other tool along with the instructions.
Include visuals when appropriate. Combining text with visuals (figures,
charts, tables) improves your documents readability. It also provides for
the "visual learner" and international readers. Remember to title and label
your visual, and refer to the visual in the text.
Use good technical writing technique. Standard techniques include
forcasting (headings, transitional language, etc.), "chunking" or modular
layout, consistent organization, correct formatting of visuals, etc.
Follow the standards expected/required by your audience. Along with
the American National Standards Institute (ANSI) guidelines covering technical
documentation, your company or client may adhere to professional standards
for written instructions. If you are unsure what standards are required,
Picking the Format that Fits the Audience
There are many different formats used in instruction sets. Each of these
targets a particular audience with a specific level of task-related expertise.
If you have done good audience analysis, you will be able to pick the appropriate
format to ensure effectiveness.
|Quick Reference Guide
||Tree Structures (Topics)
You may have noticed that novice readers, not surprisingly, need to
be led through the complete procedure. Experienced readers expect to refer
to the documentation only as needed, picking topics that fit an immediate
need. Some documents target both novice and experienced readers, who will
each use the documents differently. Finally, regardless of audience, all
technical documentation has contractual or legal elements, so complete
and accurate information is needed in all formats.
WARNING: Writing Hazard Statements
Safety information is often required in instruction sets to protect people,
property or both. To write a clear, effective warning, do the following:
Hazard statements may use different terms to warn readers. Note,
and Danger each have implied levels of hazard. Note and Caution
typically refer to information about property or use.
Danger refer to personal safety hazards. But not all readers understand
the differences. As the writer, ask yourself if the readers clearly understand
the danger and how to avoid it.
Place the warning in the document near and before the hazardous tasks
listed. Do not place them at the end of the document or on a page separate
from the hazardous task description.
Highlight the warning using appropriate visual technique. Use hazard
symbols, bold, color and other graphic and textual cues (e.g., boxes, callouts,
etc.) to get the reader's attention. Combining a visual with short text
is usually most effective.
Keep hazard statements direct, clear and accurate. Give reasons
for caution, i.e., consequences of ignoring the warning. Keep messages
short and to the point. Use active voice. Only give one warning per hazard
Follow expected/required guidelines.
Written By: George Knox © 1999