A great technical book contains all sorts of content types because different readers learn in various ways. If everyone learned in the same way, technical books would be easier to write, albeit, a bit boring. Procedures are part of the hands-on content that turns a “how” book into a “how to” book. A how book simply shows how something is done. For example, you might see a coding example that shows how to perform a technique. However, unless you actually work with that technique, it’s unlikely that you’ll truly grasp the methodology behind it.
Writing good procedures that actually work is hard. I think the point was driven home to me at an early age by a teacher who seemed to have way too much fun in class. I learned quite a bit from her simply because she made learning fun. When it came time to write a procedure, she chose making toast, which seems to be a typical example. However, when it came time to check our procedure, we each handed our papers to another student who read them aloud while the instructor performed the steps precisely as written. Many of us forgot to mention taking the bread out of the wrapper, so she’d politely try to stuff the pieces, wrapping and all, into the toaster. It was a hoot, but also a great lesson.
All authors have an issue with assuming that the person viewing the procedure knows something that doesn’t appear in the write-up. The person ends up trying to stuff the bread into the toaster without taking it out of the wrapper first. Even though the example was quite humorous in that teacher’s classroom, in real life the omission of important material is frustrating for everyone because the author truly doesn’t understand why the reader is having a problem with the procedure. I’ve gone through the process myself—many times. As I’ve matured as an author, I’ve come to realize that I need to draw the answer to the problem with my procedure out of the reader without getting the reader any more frustrated than he or she is at the moment.
Good procedures, like good newspaper articles, answer who, what, where, when, why, and how. Even that requirement seems counterintuitive. Most authors seem quite pleased when they can accomplish the “how” part of the equation. The who part of the equation is often the hardest part of the procedure. Who is performing the task? It seems like an easy question to answer, but often I need to go back through a procedure and decide who is doing what and at what time. Doing something at the wrong time is often just as bad as not doing it at all. The question of where comes into play because modern computer systems have applications that interact with each other. Deciding where the person performing the procedure is at any given moment is essential to making the procedure work as expected.
Of all the questions though, the question of why is the easiest to answer, yet the most often missed. If a person does something like an automaton, there is no feeling of accomplishment—no sense of gratification. The reader goes through the motions without understanding anything about the procedure. As a result, the information doesn’t sink in and the reader is reduced to using the procedure precisely as written to perform only the task the procedure is designed to address. The best procedures answer the question of why so that the reader can use the procedure in various ways to address a wide range of problems that the author hadn’t even considered when writing the procedure.
Procedures are important. As a hands-on tool for interacting with the user, procedures present the opportunity for the author to extend the meaningful use of a book well beyond its intended purpose. An author truly can’t aspire to do more than that! Let me know your thoughts on writing procedures at [email protected].