Difference between revisions of "Instructions"

...by students

If you are ever going to write instructions on something technical, please read this

Over the years, I've had many experiences using instructions. Some of these experiences have been good (Lego), but the majority have been terribly frustrating. At times I would spend hours searching the internet for instructions on how to do some technical task; oh, I would find instructions, but finding usable instructions was something that happened all too rarely. Below I will detail some disturbingly common mistakes that should at all costs be avoided.

Write for your audience, not for yourself.

Too often I find instructions that lead the reader blindly through a series of steps, with the expectation that nothing will go wrong and everything will magically fall into place. The reader is given no clues as to what the strings he's expected to type into the Unix terminal actually do, or even what the expected output is. The phrase "RTFM" comes to mind, but often each step only vaguely hints at what one might have to look up in a manual to understand it, or where one might begin to start looking for these manuals. I may be preaching to the choir here, but it's critical to put yourself in your audience's shoes. (Please excuse my rampant use of clichés.)

So these instructions do what?

More often than not, instructions I find will not include a sufficient introduction (or sometimes no introduction), and I will have to read and understand the instructions (sometimes in their entirety) before I finally learn what they do. Needless to say, the instructions I read often don't do the thing that I'm trying to find instructions on doing. Always have a clear introduction that says what following your instructions will accomplish.

Oh yeah, you were supposed to have the DirectX 7.1 SDK and .NET Framework 2.0 installed on a Windows ME machine.

Tell the reader what the required software and hardware is before listing all the steps, instead of, well, not at all. It's incredibly frustrating to actually try out instructions almost all the way to the end, and then find out they were doomed from the start. I usually learn this saddening news from another poor soul who's tried the instructions and failed, who had the brains and kind heart to share a "yeah, this doesn't work unless..." comment.

A Note about Graphics

In class (Technical Communication class of course), we were discussing instructions, and students were sharing their most recent examples of using instructions. Every one of the testimonials hinged on either the fact that it had useful graphics and was useful, or had not-so-useful graphics and was useless. There are simply things that text can not explain as clearly or as quickly as an image. Relevant diagrams or images can make instructions incredibly easy to follow. Lack of relevant diagrams, as many can attest, can be crippling.

I was reading instructions in a manual for a PDA and its various attachments - all the attachments were nicely labeled in a diagram, which was all well and good; until the instructions told me to connect something to the PDA that was not labeled in the diagram. What was this mystery attachment? Was it part of one of the other attachments? Was it an alternate name for one of the labeled attachments? Not one to appreciate the joys of plugging random combinations of attachments into the wall and connecting them to the university-owned Pocket PC, I promptly halted my instructional adventure.

Guidelines for Instructions

The course textbook covers several guidelines for writing good instructions.^[1] Here we will emphasize how each guideline can assist the reader and help avoid frustration.

Guideline 1: Select the Correct Technical Level

Know your audience! You'll want to write your instructions in such a way that your least technical readers can understand them. Use language that all readers can understand, defining terms beforehand as needed.

Guideline 2: Provide Introductory Information

Providing proper introductory information is key. Instructions should follow the ABC format (Abstract/Body/Conclusion). A reader should have a very good idea of what your instructions do before reading the body. This way your audience will know whether these are the instructions they are looking for.

An introduction should include:

• a purpose statement (What will following these instruction accomplish?)
• a summary of the main steps (Briefly describe what following the steps will involve.)
• a list of materials needed (Whether you use an illustration, a textual list, or reference to a list, readers need to know beforehand whether they have all the proper tools.)

Other introductory information that may help readers:

• Helpful pointers
• Definitions of terms
• Theory of how something works
• Dangers, warnings, cautions, or notes that apply to all steps

It may also be important to include what the instuctions do not do.^[2] Just remember that when readers find your instructions, they will have no idea what the instructions do unless you explicitly tell them. Naturally, the introduction is the perfect place to give this information.

Guideline 3: Use Numbered Lists in the Body

Instructions are much easier to read as lists of steps, rather than longer paragraphs. Keep in mind that readers may frequently switch their attention between your instructions and the actual task. Using numbered lists, readers can always know what step they're at.

Guideline 4: Group Steps under Task Headings

It is a good idea to group steps into logical, labeled stages, rather than using one long list with no groupings. This will help the reader both follow and better understand the process.

Guideline 5: Place One Action in a Step

For exactly the same reasons that you shouldn't put several steps in a lengthy paragraph, you should also avoid putting multiple actions in one step. Unless two actions are to be done at the same time, each step should have no more than one action. Readers shouldn't have to read through lengthy steps to figure out which part of the step they're in.

Guideline 6: Lead off Each Action Step with a Verb

Starting a step with a verb lets the reader immediately know what action is required in the step. More specifically, use verbs in the imperative (command) form, to better communicate that it's a command to the reader.^[3] The example instructions below makes frequent use of this guideline.

Guideline 7: Remove Extra Information from the Step

To avoid lengthy steps, separate the action from any extra information, and keep the action at the beginning of the step. It is common to include extra information in a "note" right after the action. Note: This note is demonstrating the use of a note.

Guideline 8: Use Bullets or Letters for Emphasis

To emphasize certain information or to make longer steps more readable, use bullets or lettered lists. (Numbered lists should be avoided if your steps are already using numbers.) You should be seeing an important trend by now: instructions should be as easy as possible to read at a glance.

Guideline 9: Emphasize Cautions, Warnings, and Dangers

Highlighting risks is an important obligation. The following three terms (in increasing order of seriousness) are commonly used to denote risks:

• Caution
• Warning
• Danger

You may choose to put cautions, warnings, and dangers immediately before the instructions; this is best when the risks are associated with the entire procedure. Another option is to placing the warnings inside the instructions, along with the steps they apply to. It is best to put the warning before the actual action.

In addition, use formatting to make any cautions/warnings/dangers visually stand out.

Guideline 10: Keep a Simple Style

Again, keeping a simple style that's easy to read is paramount. The textbook suggests techniques to accomplish this:

• Keep sentences short.
• Use informal definitions (in parentheses, so the reader doesn't have to search for them) to define terms not understood by all readers.
• Never use a "big" word (such as "paramount" or "suffice") when a more commonly known word will suffice.
• Be specific, and avoid words with multiple interpretations.

Guideline 11: Use Graphics

Words alone are not sufficient to describe the drama in this image. Similarly, instructions are often insufficient without proper graphics.

Graphics/illustrations can be extremely important, especially when your instructions deal with equipment. Use graphics for every major step if the instructions are complicated to understand without graphics, or if readers may be in a hurry, or poor at reading. Otherwise, it's often useful to include at least a few diagrams for the entire set of instructions.

Tables can also be incredibly helpful. If you can use a table to display data or matching pairs of information, then you probably should.

Guideline 12: Test Your Instructions

If possible, get someone to try out your instructions. Observed results and feedback can uncover problems that would otherwise not be fixed.

Example Instructions

Below are example instructions to demonstrate the use of the guidelines. The final section on this page will discuss this example and give additional tips.

Preface

These instructions detail the preparation of a Blizzard/McFlurry (or other similar ice cream or frozen yogurt treat) using given fast-food machinery, for the purpose of serving a customer. The presumed audience is someone completely new to the process of making this delicious item, who has no outside assistance at the moment. As such, the instructions need to be thorough, as well as easy to understand and follow. Note: These instructions assume the reader already has the required machinery and materials at hand, and has at least a vague idea of what a Blizzard is.

The Instructions

Discussion of the Example

Guideline 1: Select the Correct Technical Level

These instructions have been prefaced by a description of the audience. It's good to target the "lowest common denominator" - that is, the readers with the least technical knowledge on the subject. It's also good to not go overboard; in this example, it's reasonable to assume the reader knows what cups and spoons are.

Guideline 2: Provide Introductory Information

Before getting into the steps, the introduction includes a purpose statement (sort of), a summary of the main steps, a list of materials, definitions of unfamiliar terms, and a description of the blending machine.

Note that since this example involves a relatively simple subject, the introduction is quite brief. For more technical instructions, don't be afraid to use a long and descriptive introduction.

Guideline 3: Use Numbered Lists in the Body

Clearly the step-by-step nature of these instructions lends itself well to a list of numbered steps. Even for move complex tasks, it's helpful to list what you can as sequential steps.

Guideline 4: Group Steps under Task Headings

Without the task headings ("filling the cup", "blending", "serving"), you could imagine how hard it would to be to find your place in the list of step.

Guideline 5: Place One Action in a Step

Notice how each step has, for the most part, one action (except when there are several actions done simultaneously). Reading steps 2 through 3, one may wonder why it isn't combined into one step: "Fill cup half-way with ice cream, add toppings, then fill cup to the top with ice cream." This 1-step sentence reads exactly the same way as the 3-step sentence. But, if the reader has done only part of the step and needs to refer back to the instructions, they'll have to spend time re-reading the entire step to find out what to do next. This "Making a Blizzard" example may be too trivial to emphasize this point, but this can be an important guideline for more technical subjects.

Guideline 6: Lead off Each Action Step with a Verb

Most of the steps start off with a verb, though there are a few that start with an adverb (which has basically the same effect as starting with a verb, since a verb is soon to follow).

Guideline 7: Remove Extra Information from the Step

A few of these steps have notes underneath the actions, instead of the same sentence as the action - again, this helps keep actions short and concise.

Guideline 8: Use Bullets or Letters for Emphasis

Step 6 has two parts done simultaneously; to make the two separate parts much easier to read, they are separated into two bullets.

Guideline 9: Emphasize Cautions, Warnings, and Dangers

Really, a caution is not needed while making a Blizzard, but I added one in for demonstration purposes. Note that it may be sufficient to highlight (in this case, bold and capitalize) just the word "Caution".

Guideline 10: Keep a Simple Style

The language throughout these instructions is overly plain and simple, to avoid ambiguity and confusion.

Guideline 11: Use Graphics

Though this example does not use any graphics, it would benefit greatly from some sort of visual aid. Labeled photos of all the materials, for instance, would clearly be an asset to the reader. It would also be beneficial to illustrate how the rod in the blending machine rotates - this kind of behaviour can be difficult to describe with words, especially when using very simple language.

Guideline 12: Test Your Instructions

These example instructions were not tested, but it's good to once more highlight the importance of testing. To ensure that instructions are efficient and usable, they should be tested by someone other than the author. The simplest technique is to have a sample of test subjects follow your instructions. To test these particular instructions, one might observe readers and note if they hesitate or do something incorrectly at any particular step, and afterwards ask for feedback. Again, this process helps eliminate unclarity and ambiguity that might not occur to the author.

Further Readings

• Boogerd, Jan, Pfeiffer, William Sanborn, Technical Communication - A Practical Approach, Pearson Education Canada, Toronto, 2007.
  
• A fun interactive guide to writing instuctions - http://www.englishonline.co.uk/englishnon/literacy/literacy11-14/instruct.html
• Instructions: How to Write for Busy, Grouchy People - http://jerz.setonhill.edu/writing/technical/instructions

References

1. ↑ Boogerd, Jan, Pfeiffer, William Sanborn, Technical Communication - A Practical Approach, Pearson Education Canada, Toronto, 2007.
2. ↑ [1] Instructions: How to Write for Busy, Grouchy People
3. ↑ [2] English Online - Writing Instructions