Ricochet is the best place on the internet to discuss the issues of the day, either through commenting on posts or writing your own for our active and dynamic community in a fully moderated environment. In addition, the Ricochet Audio Network offers over 50 original podcasts with new episodes released every day.
I am a technical writer. Most technical writing comes down to documenting procedures. Many technical documents are complex, yet most are collections of relatively simple procedures. The art in technical writing is breaking everything into easily-digestible steps. Yesterday was my 60th birthday and — while I’ve only formally been a tech writer for only four years (before that my job title was software systems engineer) — I have been writing procedures since my early teens, over 45 years.
Those early procedures were wargames rules or how-to instructions (often excruciatingly bad). They were as much procedures as desk instructions on using the Navigation Console at JSC’s Mission Evaluation Room or a user guide which app developers read to use an Independent Development Environment.
Procedures are everywhere. Cookbook recipes are procedures. So are model-making how-tos. So are any set of instructions. Mowing the lawn? That can be defined in a procedure. Changing the seal on your toilet? You want a procedure to tell you how to do that. Driving to a previously unvisited destination? Driving directions are a procedure.
The world needs well-written procedures. Writing good procedures is not difficult, if you know how. So, if I am going to write a how-to, why not a how-to on how to write a procedure?
1. Define the procedure you are going to write down. Sound stupid? Not really. Most procedures are badly written because they are poorly defined. “Wash a car” is different than “wash and detail a car.” “Using Microsoft Word” is different from “insert and resize a picture in an MS Word document.” Start by framing exactly what you want the procedure to do.
Pro tip: Keep procedures simple. A procedure to use Word really is a collection of procedures to do different things in Word. (Start Word, Create a Word document, Insert a picture in a Word document, etc.)
2. Create a list of everything you need to complete the procedure. Everything. Every utensil and ingredient for a recipe. All materials and tools for a hobby project. Every element needed for a set of software instructions. You may not necessarily include the full list in your procedure, but you need to know what it includes.
Pro Tip: One magazine I wrote for has writers organize their “How To” piece into “Gather” and “Go” sections. “Gather” was the list of stuff you needed and “Go” was how to use them. I liked the idea so much, I use it every time I create a procedure to create the procedure, even if I do not write the procedure up into Gather and Go sections.
3. Execute the procedure and note the steps you take and the order in which you do them. Jot down everything you do. Record the flow of things. Note tools used and when. Note dependencies – things that have to be done before something else. Also note what stuff does not have to be done in any particular order. Take pictures or screenshots as you go.
Pro Tip: You will be amazed at the number of things you forget when you write down the steps from memory. Going through the process exposes these omissions, so you can include these otherwise forgotten steps.
4. Organize the steps you recorded in a logical sequence. Start at the beginning. Continue to the end. Sort the dependencies, so tasks which must be completed before a later task can be finished are done first. Fit the independent tasks – the ones which must be completed, but not in any particular order – so they do not interrupt the flow. (If you have twelve items requiring painting before final assembly, which can be painted at any time before assembly, group them together, to avoid repetitively bringing out the paint can and cleaning brushes.)
Pro Tip: No section of a procedure should have more than eight steps. People get confused and lose focus with a long procedure. What if you need more than eight steps? Break the procedure into up to eight sections with up to eight steps in each section. This provides 64 steps to play with. If that is not enough, create subsections with the steps within the eight sections. If 512 steps are not enough, your procedure is likely too complex.
5. Examine your outline. See where you can optimize the sequence of steps. Are there places where you are looping back and repeating work unnecessarily? Is the flow logical? Do the steps outlined require unnecessary effort? (In baking a cake to you go to the pantry several times to get separate ingredients? In building a box do you go from one end of your workbench to the other repeatedly?) Rearrange the steps to minimize movement and effort.
Pro Tip: This is where the tech writers really earn their pay. Bad procedures documents are poorly organized and poorly optimized more often than that they are poorly written. Get it organized logically and set it up to minimize wasted effort.
6. Write the procedure. Take the steps you outlined and put them on paper. A picture really is worth 1000 words in providing clarity; add images as necessary to explain the process. If you did your job in steps 1 through 5, the words should flow.
Pro Tip: Use declarative statements and active voice. Remove unnecessary words. Be direct. Write “Mix ingredients thoroughly,” not “The ingredients are to be thoroughly mixed at this stage of the process.”
7. Test the procedure. Give it to someone completely unfamiliar with the process outlined in the procedure and have them follow the instructions. Do not help the person. Once they use the procedure, get their feedback. Find what was confusing and unclear. Learn where gaps are and what you assumed they would know that they did not know.
Pro Tip: Every organization has a slow performer. Use that individual to test the procedure. If Slow Joe understands the procedure, the star performers will pick it up with no problems.
8. Rewrite. Take the feedback from your victims procedures testers and fix any deficiencies found. Repeat steps 1 through 6, redefining the procedure as necessary, adding the missing materials and steps, reorganize and re-optimize the steps or structure as necessary, and create a new draft of your procedure. Find another set of sucker-testers to test the revised procedure. Redo until exhaustion sets in, deadlines are reached, or you converge on a solution – write something which works the first time someone goes through it.
One thing you may notice: Actually writing the procedure seems like a minor part of the whole process. That is because the secret to writing a procedure is the preparation done before writing it. Step 1 (Define the procedure) may seem obvious and trivial, but it is like laying the foundation for a building. If the foundation is bad, the building will be inadequate, no matter how much effort goes into the rest of the construction.Published in