One of the most common and important 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 many infuriating experiences with badly written instructions. This chapter will show you what professionals consider the best techniques in providing instructions.
An effective set of instruction requires the following:
Clear, precise, and simple writing
A thorough understanding of the procedure in all its technical detail
The ability to put yourself in the place of the reader, the person trying to use your instructions
The ability to visualize the procedure in detail and to capture that awareness on paper
Willingness to test your instructions on the kind of person you wrote them for.
Preliminary Steps
At the beginning of a project to write a set of instructions, it is important to determine the structure or characteristics of the particular procedure you are going to write about. Here are some steps to follow:
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. Determine the number of tasks
How many tasks are there in the procedure you are writing about? Let’s use the term procedure to refer to the whole set of activities your instructions are intended to discuss. A task is a semi-independent group of actions within the procedure: for example, setting the clock on a microwave oven is one task in the big overall procedure of operating a microwave oven.
A simple procedure like changing the oil in a car contains only one task; there are no semi-independent groupings of activities. A more 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, among others.
Some instructions have only a single task, but have many steps within that single task. For example, imagine a set of instructions for assembling a kids’ swing set. In my own experience, there were more than a 130 steps! That can be a bit daunting. A good approach is to group similar and related steps into phases, and start renumbering the steps at each new phase. A phase then is a group of similar steps within a single-task procedure. In the swing-set example, setting up the frame would be a phase; anchoring the thing in the ground would be another; assembling the box swing would be still another.
3. Determine the best approach to the step-by-step discussion
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 phone-answering service, 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.
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
If you designed a set of instructions on this plan, you’d write steps for using each button or feature of the photocopier. Instructions using this tools approach are hard to make work. 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.
