Instructions—those step-by-step explanations of how to build, operate, repair, or maintain things—are one of the most common and important types of technical writing. However, for something seemingly so easy and intuitive, instructions are some of the worst-written documents you can find. You’ve probably had many infuriating experiences with badly written instructions. Hopefully, the information on this page will help you write good ones.
Good instructions require:
Instructions incorporate items such as chronological organization, headings, lists, and special notices. However, you need to plan carefully before you apply these format items, in order to write effective, usable instructions.
Good instructions begin with good preparation, which involves audience, type, organizational approach, and task analysis.
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.
Instructions can be organized by tasks or tools.
A task approach deals with the things the user needs to do. For example, the process of finding free images for a technical document might involve the following tasks: research sites with creative commons licenses, review the sites and prioritize them according to size of database and ease of use, choose one site, identify key words that explain the concept you want to illustrate, etc.
A tools approach focuses on the things with which a user needs to interact. For example, the process of using a photocopy machine would involve writing steps for using each of its tools: cancel button, enlarge/reduce button, collate/staple button, etc. 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 useful, depending on your audience analysis and your objective in writing the instructions.
Know that most instructions focus on tasks, with any necessary discussion of tools included in notes or supplementary sections such as an appendix or glossary.
Since most instructions are task-based, doing a task analysis is a key preliminary step in writing instructions. It’s important to determine the steps in the process or procedure you’re 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.
A thorough task analysis involves studying how users use the product or do the task, interviewing them, and watching them. It can also mean interviewing marketing, product development, and help desk professionals. However, sometimes you may not be able to do a thorough task analysis. Typically, product developers don’t think about documentation until rather late, and it may be difficult to get marketing, development, engineering, and programming professionals to spend enough time with you to explain the product thoroughly. So you need to try the procedure yourself, if possible, and understand that you may end up doing a certain amount of educated guesswork. The developer is more likely to review your draft and let you know if your guesswork is right.
Examine the overall procedure you are describing to determine the number of instructional tasks. A task is an independent group of actions within the procedure. For example, setting the clock on a microwave oven is one task in the overall procedure of operating a microwave oven (which would include other tasks such as setting the clock, setting the power level, using the timer, cleaning and maintaining the microwave).
A simple procedure such as changing the oil in a car contains only one task; there are no 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, which all contribute to the one task of changing the oil. However, you may be writing instructions for a complex procedure, which involves several independent tasks within the overall procedure. For example, if you were writing instructions for maintaining a car on your own, you’d have the following independent tasks in your instruction booklet: changing the oil, rotating the tires, checking the fluids, replacing the windshield wiper blades, and so on.
Task analysis can be complex; see a Sample Task Analysis to understand the precision and detail involved.
Once you have identified tasks, identify the steps within each task. As you can see, you “drill down” during the task analysis preliminary phase, to examine all aspects of the procedure in depth, so as not to miss anything critical to a user who actually needs to follow the instructions.
Finally, decide how to group tasks within a complex procedure. For example, the following are common task groupings in instructions:
Although explaining the tasks that you identify in a task analysis provides the bulk of the content for instructions, there are more pieces to formal instructions and more considerations, such as visuals, that you need to deal with when you write. Instructions contain the following parts, often in the following order. Note that inclusion of these items, as well as their order, may vary, depending on the instructions’ content, purpose, and audience.
The title for instructions should be precise and concise. Opt for “how to” or an “-ing” phrase, such as “How to Clean your Microwave” or “Maintaining Your Apple iPhone.”
With technical instructions, the date is crucial. The date enables the reader to be certain that these instructions are the most current, and if they are not, where the instructions belong in the line of documents related to this product or procedure.
A table of contents is optional. Use one if your instructions consist of multiple tasks or have multiple sections, or if they are being presented in the form of a manual.
Plan the introduction to your instructions carefully. Make sure it does any of the following things as appropriate, in whatever order is appropriate for your purpose and audience:
Although notes and warning notices should occur in the specific steps themselves, you may need to emphasize notes and warnings earlier in the instructions, especially if there is a possibility of readers ruining their equipment, wasting supplies, causing the entire procedure to fail, and/or hurting themselves. It’s fine to put important notes and warnings in two places within the instructions. Companies have been sued for lack of these special notices, for poorly written special notices, or for special notices that were out of place.
You may need to discuss background and/or theory in the preliminary material for certain kinds of instructions, so that the steps in the procedure make sense to your reader. This is a place to include technical definitions or descriptions if needed.
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, and supplies (things that are consumed in the procedure such as wood, paint, or nails). Note that you may need to specify some or all of the items, with brand names, sizes, amounts, types, model numbers, and so on.
The following schematic shows some of the initial sections and the discussion of the steps in instructions.
When you get to the actual writing of the steps, there are several things to keep in mind:
Most instructions number the tasks and steps chronologically. But there are many methods of structuring and formatting instructions, depending on your content and purpose.
Often, it is not enough simply to tell readers what to do. 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, or even more micro-level explanation of the step. This is where supplemental information, often called a gloss, becomes important. (You know the word “glossary,” which is a set of explanations of various terms. A “gloss” is a single, brief explanation.)
The problem with supplemental information, though, is that it can hide the actual step. You want the actual step—the specific actions the reader is to take—to stand out. There are at least two techniques to avoid this problem: you can split the supplement into a separate paragraph nested under the instruction, or you can bold the instruction.
When changing engine oil, always check the owner’s manual to find the correct amount and type of oil and filter needed.
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. Most instructions rely on visuals. Generally, it is good to have both text and visuals in your instructions since your audience is likely comprised of people with different learning styles.
Visuals help clarify a concept that’s difficult to explain using only words. They may be used to show how something looks unassembled, how something is constructed, and how something should look once the steps have been completed. Graphics are useful since almost everyone can understand visual instructions and see exactly what they need to complete. 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.
See a sample of screen shot visuals incorporated into a simple set of instructions on How to Make a Checklist in D2L. (Desire to Learn, D2L, is a learning management system. The checklist function helps students know what tasks need to be completed within a course module.)
Instructions use commands, action verbs, and “you” orientation. For example, “Advance the Timer button to 4.” This approach immediately clarifies the action that the user should perform. Do not use passive voice in instructions, e.g., “The Timer button is then set to 4.” With the passive voice example, a reader may misunderstand and think that the Timer button will automatically go to 4, as opposed to understanding that they have to advance the Timer themselves.
Another of the typical problems with writing style in instructions is that writers often leave out articles (a, an, the). For example, “Press Pause button on front panel to stop display of information temporarily.” Write as you would normally write a sentence, including articles.
Don’t end the instructions with the last step. A conclusion can offer a general insight, trouble shooting information (i.e. what to do if something went wrong), and/or contact information. Include whatever is appropriate to the instructions.
You may include, as appropriate, a list of references, glossary, appendix, index, or technical specifications. Back matter items provide additional information that non-technical audiences, or audiences without specific background, may need to understand how to complete the procedure.
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 feedback from others. For small or routine procedures, it may be enough to have a coworker review them, but more complex instructions should always be tested for usability
Licenses and Attributions CC licensed content, Original