Procedures in Technical Writing

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 John@JohnMuellerBooks.com.

 

Author: John

John Mueller is a freelance author and technical editor. He has writing in his blood, having produced 99 books and over 600 articles to date. The topics range from networking to artificial intelligence and from database management to heads-down programming. Some of his current books include a Web security book, discussions of how to manage big data using data science, a Windows command -line reference, and a book that shows how to build your own custom PC. His technical editing skills have helped over more than 67 authors refine the content of their manuscripts. John has provided technical editing services to both Data Based Advisor and Coast Compute magazines. He has also contributed articles to magazines such as Software Quality Connection, DevSource, InformIT, SQL Server Professional, Visual C++ Developer, Hard Core Visual Basic, asp.netPRO, Software Test and Performance, and Visual Basic Developer. Be sure to read John’s blog at http://blog.johnmuellerbooks.com/. When John isn’t working at the computer, you can find him outside in the garden, cutting wood, or generally enjoying nature. John also likes making wine and knitting. When not occupied with anything else, he makes glycerin soap and candles, which comes in handy for gift baskets. You can reach John on the Internet at John@JohnMuellerBooks.com. John is also setting up a website at http://www.johnmuellerbooks.com/. Feel free to take a look and make suggestions on how he can improve it.