ENG 333 Communication for Science and Research

Jamie Larsen, Instructor

Instructions

Writing effective instructions for multiple users can be a tricky task. As a professional, you will find yourself at times required to create instructions for peers, or for users of a product or piece of code that you have worked to help create.

These notes cover the following topics:

• Objectives
• Instruction Analysis
• Basic Sections in Instructions
• Graphics
• Overall Format Considerations
• Checklist for Revision of Instructions
• Usability Testing

This unit will prepare you to:

• Write clear instructions
• Understand a procedure in technical detail
• Analyze the instructions from a user's perspective
• Test the instructions on a user who matches your audience profile

Instruction Analysis

The structure of instructions is important to determine before writing them, and also to consider when analyzing the effectiveness of a set of instructions. The following characteristics can help guide your analysis.

Audience and Communication Situation

When defining the audience, it is important to determine demographic characteristics, such as age, education, cultural background, etc. But it is also equally important to define an audience's level of familiarity with the topic. Often, this will require some extra legwork. You may have to talk with managers of the potential users, or marketing people for the product requiring the instructions. Ask yourself, "Who knows this audience group the best?" and consult these experts to help you create instructions that will meet your target audience's needs.

Number of Tasks

First, let's define two terms. Procedure refers to an entire set of instructions. Task is a semi-independent group of actions within the procedure. For example, setting the clock on a microwave is one task in the overall procedure of operating a microwave oven. Some instructions have only one task, but they have multiple steps within that single task. Changing the oil in a car is one task with multiple steps.

It is important to determine the tasks and steps required so that you can structure instructions effectively. Imagine a set of instructions for assembling a childs' swing set. In my experience, there were more than 130 steps. This can be daunting, to say the least. A good approach to creating instructions for complex tasks is to group similar and related steps. Start renumbering a group of similar steps into sub-tasks . For example, a few sub-tasks for setting up a swing set would be setting up the frame, anchoring the frame in the ground, assembling the box swing.

Approaches to Writing Instructions

Determining how to focus your instructions is also important. You can take a task approach , or a tools approach .

In a task approach, the instructions are written to enable users to DO something. Instructions for using a phone answering machine would have sub-tasks on recording your greeting, playing back your messages, saving your message, etc.

A tools approach is designed around features of a product. This approach can sometimes be harder to make work since the name of a feature may not match the user's actual task when using it. For example, instructions on using a photocopier would have sections on the copy button, the cancel button, the enlarge/reduce button, the paper tray, and so on. A user may have two different tasks when using the paper tray. You may want to instruct users to load paper, or you may want to instruct them to pull out the paper tray in order to detect and fix a paper jam. Addressing these unrelated sub-tasks with a tools approach may not be the best method. However, you need to understand your procedure and choose the best approach based on which one will enable you to write the simplest, and clearest instructions.

Remember my motto that Less is Best . I think this can help determine which approach will help you write the most effective instructions.

Grouping of Tasks

Listing tasks, one after another, in a sequential manner may not be all that you need to do. There may be so many tasks that you must group them so that users can locate individual ones more easily. Consider novice and expert users. Expert users may need to only refresh their memories of a certain, more complicated sub-task without needing to go through prior steps in detail.

The following are common task groupings for general instructions: unpacking and setup tasks, installing and customizing tasks, basic operating tasks, routine maintenance tasks, troubleshooting tasks.

Basic Sections in Instructions

The following sections may not all need to be included in a set of instructions. Also, the order may differ than the list presented here. As you read through these sections, it is often useful to compare a set of instructions with what is here, and consider why certain sections are, and are not, included.

Introduction

Remember to focus on your audience's needs from the very beginning. You need to answer the question, "Why do I need to read this?" Be sure to include the problem your instructions helps solve, and the purpose (result) of what the user will do. A good introduction will:

• Indicate the specific procedure that will be explained, as well as the scope of coverage (i.e., what will be covered , and what will not)
• State what the audience background and level of knowledge needs to be in order to complete the instructions
• Indicate the conditions when these instructions should, and should not, be used
• Give an overview of the contents of the instructions

Caution, Warning, and Danger Notices

Effective instructions must always alert users to the possibility of errors occurring, or worse, injury. There are three levels of special notices.

1. Caution - Note that not following instructions will result in wrong results.
2. Warning - Note that errors can result in damage to equipment.
3. Danger - This is the highest level, and most important. Note that physical injury to the user may occur if the instructions are not followed exactly.

Linda Driskill, my technical writing instructor when I was an undergrad at Rice University, said, "It is not enough to say "keep off the grass" you must go further - say that there are poisonous snakes in the grass, that the bite of one can kill you, and that an alternate route around the grass exists - and show how to use it." Go the extra mile for your user - and for yourself! Remember, it is no longer buyer beware - it is seller beware.

Background or Related Theory

Sometimes instructions need a discussion of related background information or theory in order for the procedure to make sense. For example, you may have had some experience with software applets in which you define your own colors by nudging red, green, and blue slider bars around. To understand how to effectively use colors, you should have some background on color theory (e.g., what colors contrast well, what colors are distracting, etc.).

Equipment and Supplies

This is a must. Be sure to include a complete list of the things that users need to gather in order to complete the entire procedure. There is nothing more frustrating than starting a procedure, and then having to stop and go get a required tool in order to continue. Be user-friendly!

You should include equipment , the tools a user uses in the procedure (e.g., mixing bowls, spoons, hammers, drills, etc.), and supplies , the things that are consumed in the procedure (e.g., wood, paint, glue, flour, etc.). Typically, these are listed in a simple vertical one, or two, column list. Always include specifications that are relevant, such as brand names, sizes, amounts, types, model numbers, etc.

Discussion of Steps

Typically, we imagine instructions as being discussed in a linear, vertically numbered manner. And, in fact, most instructions are created using a numbered approach. However, sometimes other considerations may require that you consider using a variation of the common structure. You may consider using one of the following approaches:

• Variable order-steps are steps that can be performed in any order. Examples include troubleshooting guides that tell readers to check various things in order to detect and fix problems. A bulleted list is an appropriate format.
• Alternate steps are those where two or more ways are presented for completing a task. When you have novice and expert users for the same procedure, you may need to address their varying needs in this manner. Also, when varying conditions can affect how instructions are done will require this approach. Use bulleted lists, or insert alternatives within steps. Be sure to include lead-in text indicating that alternatives are about to be presented.
• Nested steps are needed when complex steps need to be broken down into sub-steps. Indent further and sequence the substeps differently than the sequencing of the main step (e.g., a, b, c).
• Stepless instructions are those that cannot be numbered in a logical way. These exist when a user requires less instructional-style direction, and more explanation in order to complete a task. For example, learning to swim does not lend itself to steps and tasks. You could create such a set of instructions, but ask yourself how useful would they really be. Feeling the buoyancy that water provides, and understanding that breathing in water is probably not a good idea affect how the skill of swimming is acquired. Instructions that require tactile learning are probably not geared toward the traditional, fixed-order step format.

Supplementary discussion is often needed. It is not simply enough to tell users what to do, but you must also include additional information, such as how something should look before and after a step, or what mechanical principle is behind what they are doing. The problem with supplementary discussion is that it can bury the actual step. You want the actual step, that specific actions of the user, to stand out. To avoid the problem of hiding your step in a lot of explanatory text, you can split the instruction from the supplement into separate paragraphs, or you put actual steps in bold to differentiate them from supplementary text.

Writing style is another important consideration. Most often you will use an imperative style that includes commands, or direct addresses. "You" is often used, as if you are talking to a real user - which you are. Watch using passive voice in instructions. This can lead to some weird writing. For example, "The Pause button should be depressed in order to stop the tape temporarily," seems to be about the Pause's button's mental health. Do not write in a way that leads your user to ask, "Are they talking to me?"

Also, writers of instructions tend to leave out articles. For example, "Press Pause button on front panel," sounds like a robot talking. Be sure to include all articles (a, an, the) and other words that you would normally use when talking to someone.

Graphics

Graphics are crucial for effective instructions (and for most technical writing!). If you can draw a picture of something, then you truly understand it - and better, you can explain it to just about anyone. Illustrations help users to visualize what they are supposed to be doing, and not doing. Use graphics to highlight warnings, to draw users attention to essential and critical steps, and to guide users through the procedure.

Specific information about Designing Effective Graphics may also help you with the instruction assignment.

Overall Format Considerations

Be sure to use headings to guide your users to the main sections of your instructions. You will also need sub-headings for main tasks. And, if your procedure is involved or lengthy, you may need sub-sub-headings for sub-tasks. Lists are a common format, as I discussed earlier. Remember, to include parallel lists, with each item starting the same (e.g., all verbs, all nouns - Handle, Measure, Bake).

Include all special notices. Companies have been sued for lack of warning, as well as for poorly written warnings. In a real-world context, you would have a lawyer review instructions for the public, and in particular, to help with the wording of these sections.

Spell out abbreviations and all acronyms. Do not make users guess at what you mean, because they will invariably guess incorrectly.

Checklist for Revision of Instructions

Watch out for the following problems that can typically creep into any set of instructions:

• Write a complete Introduction that explains the problem that the procedure will resolve. Provide an overview of the contents.
• Select the appropriate type of list to use and be consistent.
• Use informative headings. Generic ones are useless and space wasters.
• Highlight all special notices, especially Danger items.
• Use graphics to illustrate key actions. Remember to title graphics and refer to them within the text.
• Provide supplementary information where needed.
• Create a comprehensive list of Equipment and Supplies and also include the time required to complete the procedure, and main task.

Usability Testing

You want to be sure your instructions are accurate, and useful. Your test should check for validation, and verification. You need to consider readablity, and format too. To test your instructions, you need to gather a small sample of potential users, and ask a series of questions as they work with the procedure. Before you conduct a usability test, you should:

1. Develop a list of potential problems in your instructions (e.g., identify more complex tasks)
2. Define exactly what you are testing
3. Develop a specific set of tasks for the test
4. Decide how you are going to collect your data (e.g., someone records user responses during the test, use of a survey after the test, video tape, etc.)