The assignment for this unit also focuses on description, definition, or one of the other information structures discussed in Appendix F. These are common elements in technical writing. Rather than documents type of their own, they more commonly appear as elements or parts of other documents, such as instructions in this case. However, you can imagine description, for example, being used heavily in reports on accidents, property appraisals, and product specifications. The content, organization, and format suggestions discussed in the information-structures section will give you a good foundation to write these other kinds of documents.
In the assignment for this chapter, you actually write two assignments in one: a set of instructions and an information structure (such as description, definition, or other) integrated within those instructions. This scenario gives you experience with two key types of technical writing but in a way that saves two to three weeks in the semester. This enables you to have more time toward the end of the semester to work full time on your technical-report project.
Be sure to check out the example instructions available with this chapter:
Note: Students enrolled in the online version of TCM1603 at Austin Community College, please take the reading quiz on this chapter. (Anybody else is welcome to try it as well.)
Ultimately, however, good instruction writing not only requires these techniques but also:
Audience and situation. 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 such details. See Appendix A for discussion of audience and steps to use in defining audiences.
Most importantly, you'll need to describe your audience on a separate sheet of paper and hand that in with 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 this technical-writing course it is preferable to write for nonspecialist audiences--this is much more of a challenge to you as a writer.
Number of tasks. An important consideration is how many tasks there are in the procedure you are writing instructions for. 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 plenty of such semi-independent tasks: setting the clock; setting the power level; using the timer; cleaning and maintaining the microwave, among others. (The instructions on using a camera are organized by 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; assembling the box swing would be still another. (The instructions on installing a wall cabinet, starting on page , are organized by phases.)
Best approach to the step-by-step discussion. 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).
In a task approach to instructions on using a phone-answering machine, you'd have sections on recording your greeting, playing back your messages, saving your messages, forwarding your messages, deleting your messages. 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 sections on the copy button, the cancel button, the enlarge/reduce button, the collate/staple button, the paper tray, the 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.
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; and so on. (For the purposes of this technical writing course, you won't need to cover all of these possibilities--but in a real-world set of instructions, you would.)
As you read the following on common sections in instructions, check out the example instructions starting on page . Not all of the following sections typically found in instructions will show up in the examples, but most will.
Figure 8-1. Schematic view of instructions. Remember that this is a typical or common model for the contents and organization--many others are possible.
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, which are covered in Chapter 6. Notice how these special notices are used in the example instructions at the end of this chapter.
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. 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.
Discussion of the steps. When you get to the actual writing of the steps, there are several things to keep in mind: (1) the structure and format of those steps, (2) supplementary information that might be needed, and (3) the point of view and general writing style.
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; 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 techniques to avoid this problem: you can split the instruction from the supplement into separate paragraphs; or you can bold the instruction.
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: "Now, press the Pause button on the front panel to stop the display temporarily" and "You should be careful not to ..."
A particular problem involves use of 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?" (More detail on the passive-voice problem can be found in Appendix E.)
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.
This writing assignment asks you to include illustrations or other kinds of graphics--whatever would normally be used in the instructions. The problem of course may be that you don't have access to graphics that would be suitable for your particular instructions, and that you don't feel wildly confident in your artistic abilities. There are ways to overcome these problems! Take a look at the suggestions in Chapter 7. In that chapter, you'll see not only suggestions for creating graphics, but also requirements on their format.
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. See Chapter 5 for requirements on lists (again, remember that this course asks you to use the style and format for lists described there).
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, 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. See Chapter 6 for a complete discussion of the proper use of these special notices as well as their format and placement within instructions. (Again, in our course, we have the style and format for these notices described in that chapter).
Number, abbreviations, and symbols. Instructions also use plenty of numbers, abbreviations, and symbols. For guidelines on these, see Appendix D.
