Tag: Procedure

Working with Procedures

Procedures, a description of how to perform a task, form the backbone of most non-fiction books and even appear sometimes in fiction books. The process of doing something is the reason that many people buy a book. It’s important to realize that most people buy books to fulfill a need—often to save time and effort. Yes, it’s important to present information in the most professional manner possible, but the accuracy and completeness of the information you provide is actually more important.

Some authors make the mistake of thinking that books only contain one type of procedure. This perception can be reinforced by books that follow a certain style in order to create a book brand that offers the reader a consistent experience. However, authors can actually choose from a wide range of procedure types:

 

  • Numeric Steps: Step-by-step procedures are the kind that most authors think about immediately. This type of procedure has the benefit of clarity and of a visual presentation that the reader will understand quickly. However, they lack depth and when an author needs to explain a process in detail, numeric steps can become cumbersome and difficult to use. In addition, numeric steps are often limited to just two or three levels and some processes may require additional levels.
  • Running Commentary: The author places each step in an individual paragraph. The first sentence normally provides an overview of a more complex process that the step must fulfill. This type of procedure allows the author to provide much needed detail and to emphasize information in ways that would be difficult using numeric steps. In addition, this kind of procedure is often viewed as friendlier and more accessible by the reader (especially novices who want to learn a process in detail). Unfortunately, the reader will have a hard time finding this sort of procedure because it doesn’t generally stand out from the rest of the text. In addition, this form doesn’t offer levels, as such. It’s basically a single level procedure.
  • Outline: A complex process could be explained using an expanded outline format. Each heading is an individual step. Depth is achieved through the use of subheads and the number of layers is limited only by the number of heading levels (generally between four and six) that a book design accommodates. Readers can usually recognize this sort of procedure visually, especially if the headings include numbers to indicate steps. The problem with this format is that it tempts the author to provide too many unneeded details, a wealth of asides, and even to get completely off track.
  • Graphic: Some processes aren’t easy to describe using a written procedure. It’s possible to use a flowchart or organizational chart format to describe many processes in a manner that the reader can grasp almost immediately. The down side to this kind of procedure is that the author must be extremely terse. There is only so much space for text in a graphic procedure.
  • Hybrid: Using links makes it possible to combine approaches when necessary. For example, a graphic procedure could include references to pages that contain detailed information. The pages could then employ any of the other procedure formats to enhance the detail offered by the graphic format. In fact, it’s possible to link multiple graphic presentations so that one flows into another.


These are just a few of the common offerings at an author’s disposal. There are many ways to format a procedure so that it conveys the information the reader needs in precisely the right way. Experimenting with procedural formats will help you hone your skills and to choose just the right form for your readers. Let me know if you have any questions about writing procedures at [email protected].

 

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 [email protected].

 

Dealing with System Differences in Books

It’s unlikely that there are two computer systems on the planet that are precisely the same. Even if the two systems have precisely the same hardware and software, and the administrator configuring the systems uses an image file so that every setting is in precisely the same place, the two systems will have differences. It could be something as simple as the memory delay for one system is just a tad different than the other system. In fact, timing issues cause programmers more headaches than you might think. Environmental factors also play a role in how two systems work. The temperature in one room might be higher than another—affecting the way the systems work. Everything else considered, the users interacting with the systems will be different. The user is part of the system, after all. Therefore, no matter how hard you try to create two systems that are precisely the same, you’ll fail because there are simply too many variables to consider. These differences, no matter how small and subtle, affect how I write my books. The procedures I write for my books must work well for a wide variety of systems, including the users who are using the book to learn how to perform a task.

Let me state up front that there is always a possibility that a procedure you find in one of my books may not work on your particular system, no matter how much time and effort I put into creating the best procedure possible. I apologize in advance for any errors on my part that hinder your learning. It’s never my goal to make things difficult for anyone—quite the contrary, I take great pleasure in making your life easier. One of the reasons I created my beta reader program is to reduce errors in my books. Another reason is to reduce the chance that you’ll encounter problems with procedures in my books due to system differences. More beta readers mean more test systems and a lower probability that some oddity will get past everyone and make it into my books.

However, the fact remains that no amount of effort on my part will ever produce a procedure that always works on absolutely every system on the planet because each system is unique. I can’t possibly test the procedure on absolutely every system out there—much as hardware vendors can’t foresee potential conflicts or software vendors can’t predict a particular system combination that will cause an application to fail. In fact, given the limited resources at my disposal, it’s quite possible that you’ll encounter a problem with a procedure. When this happens, I invite you to contact me at [email protected]. We’ll work together on a solution to the problem you’re experiencing with the procedure. When a problem is severe enough, I’ll post an update for that book on my blog so that everyone can benefit. After all, the purpose of my books is to help you learn how to do something interesting with your computer system.

There are a few things you can do to reduce the potential for problems with the procedures in my books. The following list contains the difficulties that I encounter most often and solving these issues often helps my readers get back on track with the book.

  • Use the software and hardware that the book is designed to work with. Older or newer versions of software and hardware often work differently and cause the procedure to fail.
  • Read the steps carefully and verify that your display looks similar to the one in the book. Differences between my system and your system will sometimes mean that your screen will look a little different from mine, but the screens should at least look similar.
  • Make sure you have the knowledge required to use the book. I’ve been trying to become more careful in stating the knowledge a reader needs as part of the book’s introduction. If you don’t have this knowledge, you’ll find that you have a hard time learning the material.
  • Check your system for failures. In some cases, a reader’s system isn’t working right in the first place and the failure of the procedure merely mirrors this fact.


I always want to hear from my readers. Your e-mails to me brighten my day because I know someone is using the material I’ve worked so hard to create. I’m quite serious when I say, “Contact Me, Please!” Please do make sure to follow the guidelines in my Sending Comments on My Books post when sending me e-mail so that I have the information needed to help you as quickly as possible.