ITS 311: IT Communications

Chapter 9: Giving Instructions

Objectives:

This chapter discusses technical documents that tell a user how to do something. Objectives important to this chapter:

1. Definition of instructions
2. Legal issues
3. Organizing the material
4. Notes, precautions, cautions, warnings, and danger
5. List of tools and materials
6. Chronological order
7. Command voice

Concepts:

Definition of instructions

The text begins by telling us that sets of instructions are the most common kind of technical writing. Instructions are defined as a chronological set of steps in a procedure. The author tells us that they are not always numbered steps. This is true, but numbering the steps is highly recommended. Instructions are contrasted with process analyses (described in another chapter): 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

The text advises us that 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. The chapter presents five levels of such warnings, and recommends their use to prevent mishaps, problems, and disasters. These levels are discussed later in the chapter.

Organizing the material

The author makes the usual recommendations about determining the level of instruction your audience requires. 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. The author presents four structures that are recommended as being the "most reliable" on page 293.

• Arabic numbers/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. It is clearer that 1.01 comes before 1.02, while 1.10 comes after 1.09. 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.

Notes, precautions, cautions, warnings, and danger

As noted above, the author presents a system of five levels of alerts for the reader. These levels are presented as a suggestion. The definitions used for the alerts are not universal. Defining these levels for the user at the beginning of your document would be a good idea, and may avoid misunderstanding of the intensity and importance of the messages you will include in the document.

• 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, the author recommends associating a visual identifier with each of them, so they will be readily recognized in your documentation.

List of tools and materials

A list of tools and materials needed to carry out the instructions is often expected by users. It 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.

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. The author recommends using parallel constructions where possible, to improve instructions. Consider this example of poor construction:

1. Remove the access panel.
2. Remove the retaining screws.
3. 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. The first two instructions might be misunderstood if there are multiple access panels and multiple sets of retaining screws. A better way to write this:

1. Remove the printer's rear access panel.
2. Remove the fuser's retaining screws.
3. 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.