The focus for this chapter is one of the most important of all uses of technical writing—instructions. As you know, instructions are those step-by-step explanations of how to do something: how to build, operate, repair, or maintain things.
One of the most common and one of the most important uses of technical writing is instructions—those step-by-step explanations of how to do things: assemble something, operate something, repair something, or do routine maintenance on something. But for something seemingly so easy and intuitive, instructions are some of the worst-written documents you can find. Like me, you’ve probably had many infuriating experiences with badly written instructions. What follows in this chapter may not be a fool-proof, goof-proof guide to writing instructions, but it will show you what professionals consider the best techniques.
Ultimately, good instruction writing requires:
By now, you’ve probably studied headings, lists, and special notices—writing a set of instructions with these tools probably seems obvious. Just break the discussion out into numbered vertical lists and throw in some special notices at the obvious points and you’re done! Well, not quite, but that’s a great start. This chapter explores some of the features of instructions that can make them more complex. You can in turn use these considerations to plan your own instructions.
At the beginning of a project to write instructions, it’s important to determine the structure or characteristics of the particular procedure you are going to write about. Particularly in technical instructions, your understanding of the procedure could make the difference between success and failure, or at more complex levels, life and death.
Early in the process, define the audience and situation of your instructions. Remember that defining an audience means defining its level of familiarity with the topic as well as other details, including age and ability level. See the discussion of audiences and steps to use in defining audiences.
If you are in a writing course, you may need to write a description of your audience and attach that to your instructions. This will enable your instructor to assess your instructions in terms of their rightness for the intended audience. And remember too that in a technical-writing course it is preferable to write for nonspecialist audiences—much more of a challenge to you as a writer.
Next, examine the procedure you are describing to 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. Within that task are a number of steps, such as removing the plug, draining the old oil, replacing the filter, and adding the new oil. If you were writing instructions on maintaining your car yourself to save money, you would have several tasks, some which are independent, such as rotating the tires, checking the fluids, or replacing the windshield wiper blades.
A complex procedure like using a microwave oven is another example of a procedure that contains plenty of such semi-independent tasks: setting the clock; setting the power level; using the timer; and cleaning and maintaining the microwave.
There may be more to your instructions than just tasks. 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; and assembling the box swing would be still another.
Another consideration, which maybe you can’t determine early on, is how to focus your instructions. For most instructions, you can focus on tasks, or you can focus on tools (or features of tools). Your approach will depend on your overall objective in writing the instructions, and you will find that the task approach is one you will probably use most often, with the discussion of the tools included in notes or supplementary sections like a glossary.
“Use task orientation. Focus on the tasks your readers want to perform; use how to or -ing phrasing on headings.”
In a task approach (also known as task orientation) to instructions on using a phone-answering service, you’d have these sections:
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 would be these unlikely sections:
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 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.
Finally, you have to decide how your are going to group tasks if there are more than one. Simply 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:
The following is a review of the sections you’ll commonly find in instructions.
Title. Naturally you need one, and it should be concise. Avoid awkward noun strings like “Amazing Pizza Rolls Baking Instructions” and instead opt for the “how to”, such as “How to Clean Your G.E Microwave” or the gerund, or -ing word phrase, such as “Maintaining Your Apple iPhone.”
Date. With technical instructions, the date is crucial. It enables the reader to be certain that these instructions are the most current, and if they are not, where these instructions belong in the line of documents related to this product or procedure.
Table of Contents. If your instructions consist of multiple tasks or have multiple sections, or if they are being presented in the form of a manual, a table of contents is necessary.
Introduction. Plan the introduction to your instructions carefully. Make sure it does any of the following things (but not necessarily in this order) that apply to your particular instructions:
General warning, caution, danger notices. Instructions often must alert readers to the possibility of ruining their equipment, screwing up the procedure, and hurting themselves. Also, instructions must often emphasize key points or exceptions. For these situations, you use special notices—note, warning, caution, and danger notices. Typically, danger means that there is a risk of severe bodily harm or death; warning means there is actual risk of bodily harm or major damage to the product; caution means be careful here—there might be a risk; and a note is used to explain details, or tell how to trouble shoot a step within a task.
Technical background or theory. At the beginning of certain kinds of instructions (after the introduction, of course), you may need a discussion of background related to the procedure. For certain instructions, this background is critical—otherwise, the steps in the procedure make no sense. Here is where you get to show your expertise in writing technical definitions and descriptions. For example, you may have had some experience with those software applets in which you define your own colors by nudging red, green, and blue slider bars around. To really understand what you’re doing, you need to have some background on color. Similarly, you can imagine that, for certain instructions using cameras, some theory might be needed as well.
Equipment and supplies. Notice that most instructions include a list of the things you need to gather before you start the procedure. This includes equipment, the tools you use in the procedure (such as mixing bowls, spoons, bread pans, hammers, drills, and saws), and supplies, the things that are consumed in the procedure (such as wood, paint, oil, flour, and nails). In instructions, these typically are listed either in a simple vertical list or in a two-column list. Use the two-column list if you need to add some specifications to some or all of the items—for example, brand names, sizes, amounts, types, model numbers, and so on. This may be a good place to use graphics or visuals, especially if a necessary tool is a specialty item.
Discussion of the steps. When you get to the actual writing of the steps, there are several things to keep in mind:
Structure and format. Normally, we imagine a set of instructions as being formatted as vertical numbered lists. And most are in fact. Normally, you format your actual step-by-step instructions this way. There are some variations, however, as well as some other considerations:
Supplementary discussion. Often, it is not enough simply to tell readers to do this or to do that. They need additional explanatory information such as how the thing should look before and after the step; why they should care about doing this step; what mechanical principle is behind what they are doing; and even more micro-level explanation of the step—discussion of the specific actions that make up the step.
The problem with supplementary discussion, however, is that it can hide the actual step. You want the actual step—the specific actions the reader is to take—to stand out. You don’t want it all buried in a heap of words.
There are at least two techniques to avoid this problem: you can split the instruction from the supplement into separate paragraphs; or you can bold the instruction. The example below shows you a possible technique for including supplementary discussion so that it doesn’t obscure the instructions.
How to change engine oil in six steps
When changing engine oil, always check the owner’s manual to find the correct amount and type of oil and filter needed.
Caution: Be careful because the old oil may be hot and could burn you.
Bolding actual user steps in instructions. Bold text helps distinguish the actual action from the supplementary information
Writing style. The way you actually write instructions, sentence by sentence, may seem contradictory to what previous writing classes have taught you. However, notice how “real-world” instructions are written—they use a lot of imperative (command, or direct-address) kinds of writing; they use a lot of “you.” That’s entirely appropriate. You want to get in your reader’s face, get her or his full attention. For that reason, instruction-style sentences sound like these: “Press the Pause button on the front panel to stop the display temporarily” and a clarifying note might read “You should be careful not to…”
If your instructions have to be more formal, ask your teacher about preferences for using “you.” You may find that the direct address isn’t appropriate for certain contexts.
For the most effective instructions, begin each step with an action verb.
Never use the passive voice in instructions. For some weird reason, some instructions sound like this: “The Pause button should be depressed in order to stop the display temporarily.” Not only are we worried about the Pause button’s mental health, but we wonder who’s supposed to depress the thing (are you talkin’ to me?). Or consider this example: “The Timer button is then set to 3:00.” Again, as the person following these instructions, you might miss this; you might think it is simply a reference to some existing state, or you might wonder, “Are they talking to me?” Almost as bad is using the third person: “The user should then press the Pause button.” Again, it’s the old double-take: you look around the room and wonder, “Who me?”
Another of the typical problems with writing style in instructions is that people seem to want to leave out articles: “Press Pause button on front panel to stop display of information temporarily” or “Earthperson, please provide address of nearest pizza restaurant.” Why do we do this? Do we all secretly want to be robots? Anyway, be sure to include all articles (a, an, the) and other such words that we’d normally use in instructions.
Conclusion. You really don’t want to just end your instructions with the last step. A conclusion ties the process up neatly; offers trouble shooting information (i.e. what to do if something went wrong); and, if you are writing the instructions as part of your work responsibility, should include contact information.
Other Back Matter. Your set of instructions may include a list of references, a glossary or appendix, an index, or technical specifications. Items placed here are important to the overall instructions because they provide additional information that certain audiences may need, but that are not critical to understanding how to complete the procedure.
Probably more so than in any other form of writing (except maybe for comic books), graphics are crucial to instructions. Sometimes, words simply cannot explain the step. Illustrations are often critical to readers’ ability to visualize what they are supposed to do. Consider the example of car repair manuals which actually use photographs to illustrate procedures, or screen shots that demonstrate the process of using software.
In a technical writing course, instructions may require you to include illustrations or other kinds of graphics—whatever would normally be used in the instructions. Just be sure that the graphics you choose are appropriate and placed in close proximity to the steps they illustrate. Don’t make your audience flip pages to see the accompanying graphic.
If you don’t create your own graphics or images, and find them in other sources, be sure that you cite the source, preferably right below the graphic.
Headings. In your instructions, make good use of 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. Take a look at the examples at the beginning of this chapter.
Lists. Similarly, instructions typically make heavy 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. In instructions, you must alert readers to possibilities in which they may damage their equipment, waste supplies, cause the entire procedure to fail, or 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.
Replace the Guitar Neck
If you’ve followed the previous steps, your fretboard is now scalloped. The only thing left to do is put your guitar back together. To put it back together, follow these steps:
Mounting the NID
Follow these instructions to mount the network interface device (NID) on the wall:
Warning: Always wear safety glasses when using hand tools. Misuse of the tool or ricochet from power tools can result in eye injury.
Indentation of notices in instructions. In the first example, notice how the notice is indented to the text of the preceding step. In the second example, notice that the severe notice is placed at the beginning before any of the steps.
Number, abbreviations, and symbols. Instructions also use plenty of numbers, abbreviations, and symbols. Be sure you are using them correctly. Remember if your instructions pertain to a brand name product to use trademark symbols appropriately.
As you reread and revise your instructions, watch out for problems such as the following:
Some final thoughts about writing instructions. As a technical or workplace writer, your ability to write good instructions carries a number of ethical implications. Keep in mind that poorly or carelessly designed instructions leave you or your company liable for damages. They also destroy your credibility and authority. Before you submit any instructions for final review, be sure you get other eyes on them. For small or routine procedures, it may be enough to have a coworker look them over, but more complex instructions should always be tested for usability. Make sure that you have read the chapter on Usability Testing and carried out the necessary testing before your instructions go to publication and distribution.