If you want to explain technical material to ordinary people, call me.
Procedural manuals explain technical material – how to build a Viking ship, how to create a website about writing in Philadelphia, how to operate the machine you just bought – to people who need to know. If you want to write technical manuals that bridge the gap between geeks and the rest of us, here are 12 tips.
1. You need to do the work so the reader doesn’t. Write concise, accurate directions. Write shorter rather than longer. Always.
2. The more complex the task, the more you need to write it clearly.
3. Write focused, organized, sequential processes and procedures.
4. Write every single instruction in the imperative voice. That is: Tell ‘em what to do: Buy this. Pass GO. Call me at 4.
5. Start a new line and step number for every instruction. Allow only one instruction per line.
6. Explain procedures for readers who are new to the material.
7. Develop procedures that answer your readers’ questions and agenda.
8. Define every term before referring to it. Do not write, Click on the FT-40 graphic on the screen before defining the graphic.
9. After completing a draft of the instructions, close the file. Revisit it the next day, after your unconscious mind has a chance to think about it. Look for errors. Repeat as necessary.
10. Ask co-workers to test the manual before sharing it.
11. Test the procedures on prospective users, too.
12. Make certain that you generate consistent, repeatable, predictable, uniform outcomes.