Procedures: The Sacred Cow Blocking the Road

By Mike Hughes

Published: November 19, 2007

“A task analysis generates a list of procedures—plus the supporting information users need to follow them—and eventually results in a document in which sequentially numbered instructions are the dominant type of information.”

If this column’s title sounds familiar to you, the bad news is you’re getting old, but the good news is your memory hasn’t gone yet. It was the title of a presentation I gave at the STC conference in Anaheim ten years ago. However, many of the points I made in that talk are still relevant to user assistance today, so I would like to update some of them and offer some new thoughts as well.

When product teams ask technical writers to document software products, writers usually start their projects by analyzing the tasks users will perform when working with them. A task analysis generates a list of procedures—plus the supporting information users need to follow them—and eventually results in a document in which sequentially numbered instructions are the dominant type of information—neatly organized under user-centered task headings and preceded by enabling knowledge. It sounds ideal, classical even. The problem? Users don’t read procedures.

In spite of the respect and attention we give to the sequential, numbered steps that tell users how to achieve a given task, that form of information delivery just doesn’t match the typical user’s information-seeking behavior.

User Behavior

Two principles best describe how people use Help:

  • People don’t go to Help unless they feel stuck.
  • People stay in Help only until they feel unstuck.
“Put the critical information in the first three words of a sentence.”

It takes a surprisingly short amount of time for a user to feel unstuck. When I was a usability consultant, I used to advise clients to put the critical information in the first three words of a sentence. Here’s an example that demonstrates why this is important: The message “Create a directory for your XYZ product or click OK to use the default directory” often resulted in users unnecessarily creating a new directory and complaining about having to do so. The alternative, “Click OK to use XYZ product’s default directory, or if you want, create a new directory” was much more effective. Users often clicked OK without reading the whole message and suffered no harm—in fact, they did what the software developer preferred.

The three-word rule might seem restrictive, but it reflects the fact that good technical writers start instructions with a command verb that is closely followed by its direct object. Therefore, readers often have enough information to take action within three words. Unfortunately, that does not mean they have enough information to take the correct action.

A striking illustration of this fact came from a usability test I did, during which users installed a modem in a notebook computer. In one case, it was essential that a user load an installation diskette before inserting the modem into the computer’s card slot. Step 1 on the Quick Installation card was explicit about this requirement:

  1. Install the Modem Installation diskette before doing anything else.

One user read this as “Install the modem,” immediately quit reading further, and inserted the modem card into the card slot. To solve this problem, the writer reworded the instruction to say “Insert the diskette labeled…” This demonstrates how quickly users shift from reading documentation to doing something with a product. If they are this willing to abandon reading an instruction in mid-sentence, what hope is there that they will read an entire procedure?

Users’ Behavior Versus Procedures

There are some some basic mismatches between users’ behavior and the characteristics of procedures, as Table 1 shows.

Table 1—Mismatches between users’ behavior and procedure characteristics

Users… Procedures…

often have already begun a procedure, then get stuck and finally need to go to Help

start at step 1, requiring users to read—or at least skim—information that has no value to them in solving their current problem (See The MapQuest Phenomenon later in this column.)

might need to know only an important principle or rule to successfully complete a task

embed principles and rules within specific steps that require them, so users might miss them if they skip that step

are often in the wrong place in a program to perform a task when they refer to the documentation

often assume users are in the correct place to perform a task, so users might try to follow a procedure from where they are with undesirable results

might already have done something wrong that precludes the possibility of their successfully completing the procedure by following the instructions

often assume the right conditions for performing a task are in place, with the result that the instructions seem wrong to users and frustrate them

want information in the smallest chunks possible

deliver information about an entire task at once

Note—The last characteristic summarizes the basic mismatch between users’ needs and procedural characteristics: Users don’t want to know the whole answer; they just want to know the small part that has them stuck.

Some Practical Implications for Help

Wait, don’t stop writing procedures! Let’s just think differently about how we write them and how we present them. The discussions that follow provide some tips for mitigating some of the mismatches between user behavior and procedure characteristics.

The Choice Table

“A choice table is a simple, yet elegant device for displaying useful information in a procedure in such a way that frenzied, time-constrained users can easily scan it.”

My wife thinks the Nobel Prize committee should give awards to people who really contribute to society, such as the inventor of the zip-lock bag. Thinking along similar lines, I would give a prize to whoever invented multi-level undo and the choice table.

A choice table is a simple, yet elegant device for displaying useful information in a procedure in such a way that frenzied, time-constrained users can easily scan it. Additionally, choice tables can eliminate the preponderance of verbiage that describes obvious interactions with a user interface. Consider the procedure that Figure 1 shows.

Figure 1—A step-by-step procedure

Step-by-step procedure

Now, let’s look at how that same procedure can benefit from using a choice table, as shown in Figure 2.

Figure 2—A procedure with a choice table

Procedure with a choice table

A couple of things to note:

  • A user can easily scan the references to specific fields in a user interface in the second example’s choice table. In the first example, the fields are buried within the instructions.
  • Using a choice table helps writers avoid specifying obvious actions such as type and click and stay focused on value-added content.

The MapQuest Phenomenon

“If a user is already viewing the relevant topic when she clicks Help, navigation instructions are a waste of time.”

Have you ever noticed that, when you get directions from a Web map application like MapQuest, the first half of the page tells you how to get out of your own neighborhood? In all likelihood, you already know how to do that. A similar situation can occur in online Help with context-sensitive links. If a user is already viewing the relevant topic when she clicks Help, navigation instructions are a waste of time. On the other hand, if a user gets to a topic through the Help table of contents, index, or search, she’ll need those navigation instructions. This is not a big problem if the navigation involves just a single step. However, for some multi-console systems, navigation instructions can be quite complex, because a user can navigate in a number of different ways, depending on which console she might be working from.

The example in Figure 3 shows how you can pull such steps out of the procedure for a task by creating a special topic for navigation, then making it a prerequisite for the procedure. Now users who are already in the right place to perform a task are not confronted by a bunch of unnecessary instructions—in effect, the directions for how to get out of their own neighborhoods.

Figure 3—Prerequisites for a procedure

Prerequisites for a procedure

This technique is not limited to just navigation. You can use it in any situation in which you want to keep a procedure focused on a clearly defined user and a specific task and deal with exceptional cases through linked information.

Non-sequential Task Information

“Sometimes users just need a quick overview of what they can do or some critical tips for using an application.”

Writers tend to favor procedures, because they know users are task oriented. However, not all tasks are sequentially constrained. And sometimes users just need a quick overview of what they can do or some critical tips for using an application. (See my column “Anatomy of a Help File” for a fuller discussion of task support clusters and keystone concepts.) Figure 4 shows a context-sensitive link’s target topic, which gives a lot of task-oriented information, but does not offer a step-by-step procedure.

Figure 4—Target topic

Target topic

Conclusion

“Procedural information must accommodate a reader…who has already figured out how to complete steps 1 through 4 before ever going to Help….”

Users do not remain in online Help for long periods of time. So, not only must Help topics be modular and self-contained, elements within topics must be directly accessible and self-contained as well. Procedural information must accommodate a reader, for example, who has already figured out how to complete steps 1 through 4 before ever going to Help and would be discouraged from continuing to read the Help if she felt she must wade though instructions on how to do stuff she has already done or information she already knows.

Using choice tables and tailoring information for primary users won’t keep users in the Help for longer periods of time, but it does ensure they’ll get to the information they need in the brief period of time they are willing to be there at all.

4 Comments

I always used my husband as my conceptual typical male user when writing user instructions: He reads a few sentences or at most 2 paragraphs, flips through the instructions looking at the pictures and diagrams, then starts putting something together or installing it.

When he has a problem, such as 2 legs pointing up and 2 pointing down, he tells me to read the instructions and tell him what he did wrong. That is how many guys and techie gals like my daughter want to use instructions, Help, or other user assistance:

Don’t waste my time! Tell me right now:

  • Where am I now?
  • What did I do wrong or not do?
  • How do I fix it immediately?

We have to figure out how to give them that information as quickly as possible.

The context-based approach you describe is also advocated by Kathy Sierra, author of the “Head First” series of computer instruction manuals and primary contributor to the—now sadly discontinued—“Creating Passionate Users” blog. I agree that the way in which we learn is strongly influenced by what we already know.

Although I like the choice table as a way of simplifying the presentation of procedures, the descriptions in your example aren’t clear. For example, for the Comment option, the description reads “Provides a description of the policy,” which sounds to me as though the description is generated by the software instead of by the user.

Good ideas…and thanks for the information. But I would love to see it in plain English.

Sentences like this are monsters to get through:

“A task analysis generates a list of procedures—plus the supporting information users need to follow them—and eventually results in a document in which sequentially numbered instructions are the dominant type of information—neatly organized under user-centered task headings and preceded by enabling knowledge.”

Whew! It’s so full of Latin, it sounds like a Sunday sermon by an Italian priest—in Rome.

If you break up sentences and simplify words, this could be a worthwhile chunk of instruction we can grasp more easily.

Thanks for the tip on choice tables! Much easier to quickly locate information!

Join the Discussion

Asterisks (*) indicate required information.