Instruction

Principles for Writing Instructions and Process Documentation

First of all I don’t know why anyone wants to write instructions or documentation when half the population won’t read them and we all know which half. Haha I’m just kidding. We’re living in a golden age of gender equality and I will be the first to admit that women are just as capable of not reading the instructions as men are. Any instructions you can ignore, I can ignore better. That is the definition of fourth-wave feminism.

Instruction-writing can be pretty tough because in order to write instructions or process documentation, one has to be an expert in the thing they are instructing on or the process they are documenting. Ideally, the writer is the person who knows the most about it. But then, the document must be written for a person who has no knowledge of the subject, so the writer—the expert—must be able to put themself in the position of their very opposite, a beginner. The instruction must contain enough information to get the user through the process without getting lost or messing up while also being as succinct as possible so the user doesn’t peel off from tedium and try to figure it out themself. Instruction needs to be written in an authoritative tone, but also shouldn’t talk down to the end user. It’s a whole thing.

Personally, I love writing process documentation; this is because I’m an obnoxious human being who loves telling other people what to do. Just kidding, kind of, it’s because I like things to be clearly spelled out so all the people who are in an endeavor together share a common understanding of that endeavor. Which might also be part of being an obnoxious human being.

Everybody has shorthand. Okay: Let me tell you about a time I annoyed everybody by demanding better process documentation. I was speaking with a group of people at a company where I worked about updating the employee handbook and one of the items for discussion was dress/appearance and one of the subitems stated that hairstyle had to be “professional.” Nobody but me had a problem with that. I said: “But we need to define what a professional hairstyle is,” and somebody said back, “No we don’t, people know what that means,” and then yet another person said, “We can leave it up to individual personnel managers to tell staff when their hairstyle is not professional.” 

These are actually great instructions for how to make sure you get sued.

In this example, the shorthand was the word “professional” and everyone in the room (except me I guess) believed they knew exactly what that meant with regard to hairstyles. However, I would be willing to bet if I had asked everyone in the room to (separately) write down their definition of “professional hairstyle” that, first, a number of people in the room would not have had an easy time doing it and, second, that everyone would have given a different answer. 

I was an annoying butthead about it and we ended up with something like “hair should be clean and well-groomed” and perhaps there was a suggestion that hair should not be dyed any color that doesn’t occur in nature. Joke’s on them, all colors occur in nature. Where do they think colors come from? The spectrum of light. The sun. Nature.

Anyway, everybody has shorthand that we use to get through life because spelling everything out to the degree that no shorthand is ever used is simply not efficient. Language itself is shorthand. It’s way easier to make people understand what you want or need when you can tell them then when you can’t. Today’s Shelf Life on instruction writing is first going to go a bit into the mental shorthand of getting things done, because I think it’s important to understand before writing instructions.

The following instructions (not related to one another) all rely on the recipient of the instruction (you) understanding the same shorthand as me:

1. Copy this sentence and paste it into a Google search.

2. Number each page in nonrepro, including blanks and blind folios.

The instruction number 1 probably made sense to most people reading. I suspect everyone who reads this could follow the instruction, carry it out, and get the same result as everyone else reading and following the instruction. However, it does rely on the user to understand how to copy text to the computer’s clipboard, how to navigate to Google in a web browser, and how (and where) to paste text from the computer’s clipboard. 

Instruction 2 may have made sense to a few people reading but I believe most people would not know what to do, how to carry out that instruction, or perhaps even what it’s asking. The second instruction relies on the user to already have a fairly deep knowledge of publishing and printing practices, like:

• What nonrepro means in context—a pen or pencil that writes in a nonreproducible color, that is, a color that cannot be picked up by the printer’s camera.

• What blanks are—most people could probably guess this means blank pages.

• What blind folios are—readers of Shelf Life may recall from All Fronts Matter that a blind folio is a page with content but no page number, like a photo spread or a frontispiece.

This instruction is telling the user to write the page number of each page in a manuscript in a nonreproducible ink or lead color. If you ever have to send a book to a printer as camera-ready copy—a hard copy to be photographed and reproduced exactly as-is, rather than sending a digital file—you have to number the pages that don’t already have numbers printed on them (like the front matter, blank pages, photo pages, and so on) in the event the person at the printer slips on a banana peel while carrying the manuscript and all the pages go flying up in the air and they have to put them back in order. It’s a very real danger I guess.

That’s a very specific shorthand that only people who work in publishing—in fact, the subset who work in production and, still further, the subset of that subset who have handled or still today handle camera-ready copy—would know.

All that is to illustrate the first and perhaps most important principle of instruction-writing, which is: You have to know up front, before beginning, what level of shorthand you to expect your user to bring to their reading of the instruction. That is the lowest common denominator and the most-specialized level of shorthand you can use in your instructions. Everything that occurs at a higher level of specialization than that agreed-upon shorthand, or shared knowledge, must be explained.

This is why consumer electronic instructions are so dense and and obtuse and treat the reader like maybe you’ve never seen a television before in your life—the manufacturer can’t assume that the end user knows anything because they’re selling this piece of consumer electronic to anyone, they have zero control over who will read that instruction, so they need to write it at a level that literally anyone can understand, given a level of fluency in the language.

On the other hand, if you came into my work and I handed you some instructions on how to do a task, those instructions would be written using a lot of shorthand that relies on shared understanding that everyone at my company has; if you work there, I can assume stuff like:

• You know how to use a Windows computer and Microsoft Office software.

• You know how to navigate our internal system of storage drives.

• You know who Cleveland is.

So when the instructions say, “If this doesn’t work, call Cleveland for help” that makes perfect sense to everyone at my company and zero sense to everyone who isn’t.

The second principle of instruction-writing that I’m going to share is: Not everyone learns the same way. There are four main types of learning:

• Visual (learn by seeing or watching);

• Auditory (learn by hearing or listening);

• Kinesthetic (learn by doing); and

• Reading/writing (learn by reading instructions or taking notes).

Now: If you are tasked with writing instructions or process documentation, it’s fair to assume that people will use it even if reading instructions is not their preferred learning style. Instructions, in my opinion anyway, cover the people who learn well by reading and those who learn well by doing, because they’ll take the instructions and walk themself through it once or twice using the instructions and then they’ll have it. Excellent.

It can really help visual and auditory learners to create and include illustrations and video in your instructions. Now: I know as well as anybody can know that authors are not always good at creating illustrations. These aren’t the same skill and not all of us have both. That’s okay! Because often the most helpful illustration you can make for process documentation is a screenshot (assuming something is being done on a computer) or a photograph (if whatever the task is, is not done on a computer). Just get an image that shows a state referenced in the instructions, for instance: 

• “Roll the dough out into a sheet about 9 inches tall by 13 inches long”—take a photo of the dough rolled out like that.

• “Click on ‘File’ and then, from the flyout menu, select ‘Upload’”—take a screenshot of this state.

When I make instructional documentation for people on anything that’s done with a computer, I like to do a video capture: I record my screen while I’m doing the action or series of actions, and I speak into my microphone to narrate the action I’m doing. This is really easy to do with built-in functionality of recent Windows operating systems or with free software like OBS.

You need zero artistic skill to make graphic illustrations or video as an aid to your instructions, so I highly recommend it especially for complex steps.

Principle three of writing instructions: Don’t leave anything out. This is easier said than done, because as the expert in whatever the thing is that you’re instructing on, you probably do it all the time, on autopilot, without thinking too much about it. It’s easy to gloss over small steps, simple steps, and optional steps that don’t need to be done every time. Don’t gloss over them!

Also, don’t assume your end user knows something unless it’s part of that agreed-upon shorthand we talked about earlier. An example I have cited in Shelf Life before is, I used to edit cookbooks for a large publisher and I would occasionally see recipes that omitted steps because it was just assumed that any idiot would know to do that—for instance, “boil the potatoes.” Do I take the skins off first? Do I cut the potatoes up? Or am I just throwing 3 skin-on, in-tact russet potatoes into a pot of boiling water? Do I salt the water? I am that idiot who doesn’t know to do that. 

Wherever there’s room for ambiguity, err on the side of putting in more information than less. If you don’t think the “more information” is in scope for your instruction, link out to it or otherwise just indicate something should have already been done.

For instance, if a recipe calls for “3 strips bacon” and then instructs me to add that to a salad, I need to know—was it cooked? Diced? Do I just add a bunch of uncooked bacon into the salad straight out of the package? But if the recipe writer does not wish to walk me through cooking and dicing the bacon, that’s fine—their ingredient list can call for “3 strips bacon, cooked according to package instructions and diced.” That gives me the information I need to get it right but without the writer having to walk me through all the steps of that subtask.

If you’re still on the fence about whether to spell out the instructions of a subtask or not, another option is to put them in an appendix to your instructions. Just go down to the end of your document, spell out all the steps there, name your appendix something obvious like “Cooking Bacon,” and then use your word processor’s linking function to drop a link to the appendix in the main text where the user will need it.

Finally, when you have completed your instructions to the best of your ability, you need to test them before release. Depending on how official your “release” is, testing could mean different things. You don’t need to line up a panel of test users for your document on how to send FedEx packages if you’re going to be at your desk for people to come ask if you have questions; but if you’re going to print these instructions in a booklet and send them out in the package with a product, then you need to undertake testing to make sure they’re error free, usable, comprehensive, and correct.

Regardless how large is your launch, I recommend at least these three steps:

First, if your schedule allows, step away for a day or two and then use the instructions yourself. Channel your inner Catherine and pretend like you have never known how to do anything in your life and then follow your own instructions step by painstaking step to make sure you get the correct result.

Second, get a user who knows the process well (if this user exists) to read the instructions for sense and test them. Ask them to follow the instructions specifically and make notes for you if they skip any steps, or do anything additional that wasn’t in your documentation.

Third, find a user who does not know the process at all—your target audience—and have them use the instructions to see if they get the correct end result. Ask them to write down any clarifying questions they have for you and share their notes on the process with you. Ask them to attempt the entire process without your help, just using the provided instructions. They should let you know if there was somewhere in the process they had to guess or figure something out for themself. Don’t intervene unless they get good and truly stuck. 

If they do, go to jail. Go directly to jail, do not pass go, do not collect $200. Your other test user (the one who knows the process well) should also go to jail. When you both get out of jail, revise your instructions.

---

If you have questions that you'd like to see answered in Shelf Life, ideas for topics that you'd like to explore, or feedback on the newsletter, please feel free to contact me. I would love to hear from you.

For more information about who I am, what I do, and, most important, what my dog looks like, please visit my website.

After you have read a few posts, if you find that you're enjoying Shelf Life, please recommend it to your word-oriented friends.