In this lesson, we are talking about Standard Operating
Policy documents. Objectives important
to this chapter:
- Definition of instructions
- Legal issues
- Organizing the material
- Notes, precautions, cautions, warnings, and danger
- List of tools and materials
- Chronological order
- Command voice
Concepts:
Definition of instructions
Sets of instructions are
the most common kind of technical writing. Instructions are defined as
a chronological
set of steps in a procedure. They are
not always numbered steps, but numbering the steps is highly
recommended.
Instructions are contrasted with process analyses: instructions use active voice to tell a reader how to
do something, while
a process
analysis
describes what other people do and what the results may be. Process
analyses may be more like telling a story about people and
events, while instructions tend to be more like a series of commands.
Legal issues
Good instructions provide some measure of protection
from lawsuits. Instructions should include appropriate warnings about
the potential danger a product may present when used improperly.
Organizing the material
The usual recommendations about determining the level
of instruction your audience requires apply to procedures. Instructions become very unclear when
the writer assumes knowledge that the user does not
have. When in doubt, explain more rather than less.
Use clear organization to make
it easier for a knowledgeable user to skim over familiar material.
As noted above, it is recommended to number the steps in a set of instructions.
A simple numbered list is sufficient in many cases. When the instructions
are complex, a standard outline structure is recommended. Here are four structures that are recommended as being the "most reliable":
- Arabic/Letters - Arabic numbers are used for each section, and letters
are used for subsections
- Digit-dot-digit Decimal System - Sections are numbered with successive
Arabic numbers, a dot and a zero (e.g. 1.0). Subsections will have
the same number as their parent section, and change the zero to successive
numbers (e.g. 1.1, 1.2, 1.3). If subsections need further division,
more dots and numbers are added (e.g. 1.1.1, 1.1.2, 1.1.3). This system
is clear, but can be hard to follow if the numbers are too long. Also,
some users are confused if a section has ten subsections. They may
wonder if 1.1 is the same subsection as 1.10.
- Digit-dot-zero-digit Decimal System - Like the system above, but
subsections are given leading zeros (e.g. 1.01, 1.02). This avoids
some confusion that can be found in the system above: 1.01 and 1.10
are visually different enough to avoid confusion. A drawback may be
that the writer should determine the complexity of the outline first,
to determine how many leading zeros are needed. The same number of
leading zeros should be used in each case for consistency.
- Digit-dash-digit System - A variation on the first
decimal system that uses dashes instead of dots (e.g. 1-1, 1-2, 1-3).
In this variation,
the author starts with 1-1 instead of 1-0, which is why it is not a
decimal system. Either variation of this method can be correct, as
long as the writer is consistent. For some people, this one is more readable.
Notes, precautions, cautions, warnings, and danger
Some organizations may use a system of five levels
of alerts for the reader. The levels below are presented
as a suggestion. The definitions used for the alerts are not universal.
Defining these levels
for the user may avoid misunderstanding of the intensity and importance
of the message.
- Notes - additional information that may be helpful to the user following
the instructions
- Precautions - alerts to possible problems that
may be avoided with the information provided; may reference avoiding
minor damage to property or equipment
- Cautions - alerts to possible damage to property
- Warnings - alerts about possible health and safety issues
- Danger statements - alerts about possible risk
of loss of life
In addition to this graduated scale of alerts, it is recommended that you associate a visual identifier with each of them, so they will be readily
recognized in your documentation.
List of tools and materials
When working with hardware, a list of tools and materials needed to carry out the instructions is
expected, and should precede the instructions themselves. In the case of
unusual or specialized equipment, illustrations are recommended to make the
list clear. If, for example, the reader must obtain a specific part to repair
a device, a picture of the part, the part number, and a recommended supplier may all need to be provided. Video of an installation may help enormously.
Chronological order
When describing a mechanism, the technical writer has some choices in
the order of presentation of material. When writing instructions,
the steps must be put in chronological order: the order
in which they are to be carried out. Instructions written in any other order
will be confusing at best, and may cause the reader to damage equipment,
or suffer injury.
Command voice
Instructions are written as commands. They must be clear,
detailed, and sequential. Use parallel constructions where possible, to improve instructions. For example, this one does not use parallel construction:
- Remove the access panel.
- Remove the retaining screws.
- The fuser may now be removed.
In the example above, the third instruction uses passive voice, and does
not deliver on the reader's expectation of a simple instruction. A better
way
to write this:
- Remove the printer's rear access panel.
- Remove the fuser's retaining screws.
- Remove the fuser from the printer.
This set of instructions uses the same (parallel) word pattern three times.
It also includes a reference to the location of the parts to remove. Illustrations of the actions would make the instructions better than just text.
