7.8 Instructions

One of the most common uses of technical writing is to provide instructions, those step-by-step explanations of how to assemble, operate, repair, or do routine maintenance on something. Although they may seems intuitive and simple to write, instructions are some of the worst-written documents you can find. Most of us have probably had frustrating experiences trying to use poorly written instructions to complete a task or troubleshoot an issue.  But consequences can be much worse than a bit of frustration, especially if engaging in a process that contains risks, or for which the outcome is serious.

Creating effective set of instruction requires the author to have the following:

• A thorough understanding of the procedure in all its technical detail and
• The ability to convey that understanding clearly, precisely and straightforwardly in written and visual form
• An understanding of the purpose and perspective of the person trying to use your instructions
• Willingness to test your instructions on the kind of person you wrote them for.

Preliminary Steps

As you prepare to write a set of instructions, do the kind of task and audience analysis you would do for any other kind of writing.

1. Do a careful audience and task analysis

Early in the process, define the audience and situation of your instructions. Remember that defining an audience means defining the level of familiarity your readers have with the topic.

2. Identify Procedure, Tasks, and Steps

Let’s call the overall purpose that the reader want to achieve the procedure. Your instructions will let them know how to complete the procedure as a whole. Within that procedure, there may be a number of tasks.  A task is a semi-independent group of actions or steps within the procedure.

A simple procedure like changing the oil in a car contains only one task, with several steps; there are no semi-independent groupings of activities. It is part of the more complex procedure of maintaining your vehicle, which contains many tasks (flushing transmission, rotating tires, etc), each of which requires several steps. Another complex procedure like using a microwave oven contains several semi-independent tasks:  setting the clock; setting the power level; using the timer; cleaning and maintaining the microwave, and so on.

3.  Determine the best approach 

For most instructions, you can focus on tasks, or you can focus on tools (or features of tools).  In a task approach (also known as task orientation) to instructions on using a message retrieval system, you’d have these sections:

• • Recording your greeting
  • Playing back your messages
  • Saving your messages
  • Forwarding your messages
  • Deleting your messages, and so on

These are tasks—the typical things we’d want to do with the machine. Performing each of these tasks entails completing several steps.

On the other hand, in a tools approach to instructions on using a photocopier, there likely would be sections on how to use specific features:

• • Copy button
  • Cancel button
  • Enlarge/reduce button
  • Collate/staple button
  • Copy-size button, and so on

Using a tools approach, you’d write steps for using each button or feature of the photocopier. This approach can be challenging, as sometimes, the name of the button doesn’t quite match the task it is associated with; sometimes you have to use more than just the one button to accomplish the task. Still, there can be times when the tools/feature approach may be preferable.

4.  Design groupings of tasks

Listing tasks may not be all that you need to do. There may be so many tasks that you must group them so that readers can find individual ones more easily. For example, the following are common task groupings in instructions:

• • Unpacking and setup tasks
  • Installing and customizing tasks
  • Basic operating tasks
  • Routine maintenance tasks
  • Troubleshooting tasks.

Writing Style

Placing the key user steps in bold can a very helpful way to signal clearly what the reader needs to do.  You can either place the command verb or the key components in bold to highlight them for the reader. Consider instructions you have read for navigating a website or performing a task in a particular software. The instructions might use bold to highlight the specific things the reader needs to find like this:

Use the active voice to clearly indicate what the reader should do. Using passive voice in instructions can be problematic. For example: “The Pause button should be pressed in order to stop the display temporarily” makes one wonder how the button might be pressed and by whom? It would be more helpful to indicate that the reader should “press the Pause button.”  Consider this passive example: “The Timer button is then set to 3:00.” Again, one might ask, “is set by whom? how?” Is this somehow done automatically? Am I supposed to do this?   Instructions usually use command verb forms and “you” to make it perfectly clear what the reader should do.

Illustrating Your Instructions

Visual illustrations often accompany written instructions to “show” as well as “tell” the reader what to do. Sometimes, words alone cannot fully explain the step, or visuals can reduce the number of words required. Illustrations are often critical to the readers’ ability to visualize what they are supposed to do.  Graphics should represent the image from the reader’s perspective.

Formatting Your Instructions

Since people rarely want to read instructions, but often have to, format your instructions to enhance readability for the reluctant reader. Try to make your reader want to read them, or at least not resistant to the idea of consulting them.  Highly readable format will allow readers who have figured out some of the instructions on their own to skip to the section where they are stuck.  Use what you have learned about document design and visual rhetoric in chapter 3 to create effective and readable instructions:

Headings: normally, you’d want headings for any background section you might have, the equipment and supplies section, a general heading for the actual instructions section, and subheadings for the individual tasks or phases within that section.

Lists: similarly, instructions typically make extensive use of lists, particularly numbered vertical lists for the actual step-by-step explanations. Simple vertical lists or two-column lists are usually good for the equipment and supplies section. In-sentence lists are good whenever you give an overview of things to come.

Special Notices:  you may have to alert readers to possibilities in which they may damage their equipment, waste supplies, cause the entire procedure to fail, injure themselves or others—even seriously or fatally. Companies have been sued for lack of these special notices, for poorly written special notices, or for special notices that were out of place.