Latest posts by techwriter (see all)
- Test Your Knowledge of 4 Basic Fonts – Drag & Drop - January 27, 2017
- How NOT to Design a Web Site - January 25, 2017
- Hazards of Poorly Written Technical Documentation - December 26, 2016
If you saw the movie Apollo 13, you might remember a scene when they were trying to figure out a solution to the air purification problem: Someone was on his back in a mock-up of the spacecraft, manual in hand, figuring out some of the details of the plumbing. What if the writer of that document had been careless, not making the effort to be correct and unambiguous? That writer wasn’t careless, and they came up with an arrangement that enabled the crew to survive.
Sometimes writing good instructions is really important. Poor instructions, at best, are irritating, the subject of Dad-tangled-in-a-bicycle-at-Christmas cartoons.
Instructions are steps a reader follows to accomplish something. Good instructions are always more effective than poor ones. Fortunately, good instructions aren’t hard to write.
Pay attention to the following to write good instructions:
- Introduce each set of steps with a description of what the steps will accomplish. “To access the control switch.”
- If the order of the steps matters, number the steps. If the order doesn’t matter, use bullets.
- Write each step using a simple sentence in the present imperative. “Pry off the clip with a screwdriver or similar tool.”
- Then tell the result. Stay with the present tense. “The panel pops up.” This gives confirmation that the reader followed the instruction correctly.
- Put only one thing to do in each step. (Okay, you can add something closely associated with the action, like “…and press Enter.”)
- If you can, include an illustration after the instruction. You might be tempted to skip the illustration, but don’t. In some (many) cases, readers choose to rely on the illustrations without reading the text. Create the illustrations with this in mind.
- Divide the steps into groups of nine or fewer, if possible.
Here are a few other tips:
- Strive for unambiguity. Aim for only one possible meaning, easily understood. Try to think of how the instruction might be misinterpreted, and prevent that. The goal of every step is that the reader understand immediately what to do.
- If you can, watch someone follow the instructions. If they get something wrong, it’s the fault of the instructions. Fix.
- Proofread! PROOFREAD! PROOF-READ! (Imagine that duck changing his mantra to “proofread!”) Make this an ironclad rule. Proofread everything you write, even email. Get into the habit of looking for goofs.
There you have it. Writing clear instructions can change your life. Maybe even save someone’s.
Good written communication saves time, reduces frustration, and prevents costly misunderstandings. You can find more tips on writing well at http://writing-rag.com/?p=1.