There are few worse ideas in technical communication than the idea that procedures have prerequisites. There are no prerequisites. There are only steps.
To illustrate: Last weekend I paid a visit to some family members who were camping at a nearby campground. They were struggling to inflate the new air mattress they had bought. The mattress had an integrated foot pump, but no matter how they pumped, the mattress refused to fill with air.
Several of us took our turns trying. Each of us read the instructions and did what they said to do, all to no effect. The decision was eventually made to return the mattress to the store, and discussion turned to whether to go home or sleep on the ground.
I, however, decided to apply my long experience of analysing bad user documentation to trying to figure out if the fault lay in the instructions rather than the mattress. Sure enough, it did. Earlier in the document, right under the safety bumpf, was a small section call “Preparation”. It was printed in reverse — white on black. It said that before inflating you had to close a valve that was located on the far end of the mattress — as far as it could possibly be from the built-in foot pump.
Once we closed the valve, we were able to inflate the mattress.
Bad product design. Bad information design.
Yes, this is a stupid piece of product design. Why not put the valve in the same place as the foot pump so that it would be obvious that it needed to be closed?
But it is an equally bad piece of information design. I wonder if the person who wrote the instructions imagined that by putting the “Preparation” section in reverse type they were making it more prominent and ensuring it would be read. If so, they were wrong. If anything, it made it look like a particularly dire part of the safety warnings that no one reads. It helped ensure that it was almost certain to be ignored.
But the problem is not whether this attempt to make the preparation section more noticeable succeeded or failed. The problem is that there should never have been a preparation section in the first place. Step one of the inflation instructions should have been:
1. Close the valve at the other end of the mattress.
That is all that was required to make these instructions work. That is all that would have been required to save several people wasting a bunch of time and effort trying to inflate a mattress when they could otherwise have been relaxing round the campfire.
There are no prerequisites. The thing you have to do first is the first thing you have to do. It is step one.
People skip straight to Step 1.
People do not read instruction sheets through from the beginning. They skip over the lawyer’s bumph and scan for a heading that indicates the procedure they want to perform. They then skip over any introductory material under that heading and go straight to the paragraph that begins with
1.
That’s what I do. That’s what you do. That’s what everybody does.
If there is a section in there that says “Prerequisites” or “Preparation” WE DID NOT READ IT. We skipped right past it. We did not see it. We did not do it.
There are no prerequisites. The first thing we read is Step 1.
Procedures belong to the task, not the product
Some might argue that in some cases the procedure for machine A begins at a certain point, but that the user needs to make sure that some stuff has been done on machine B first. In this case, the machine A stuff is the procedure for machine A and the machine B stuff is the prerequisite.
But this is to mistake the procedure for a feature of the machine. The procedure is a feature of the user’s task. If the user’s task involves first doing something to machine B and then doing something to machine A, then that task has one procedure and it starts with the first thing they have to do on machine B.
If it might have been done already, tell them to check
Some might argue that the prerequisites may already have been done, or may have been done by someone else. That may be true, but if they are presented separately from the procedure, chances are they won’t be done by anybody and the procedure will fail. If the prerequisites may already have been done, here is how you write step 1:
1. Check to see if the valve at the other end of the mattress is closed. If it is open, close it.
To avoid repetition, link to another procedure
Some might object that the procedure for performing the prerequisites is elsewhere and they don’t want to repeat it. Okay, then write step one like this:
1. Check to see if the valve at the other end of the mattress is closed. If it is open, close it by following the instructions in section A.
Use the right reuse techniques
Some might argue that they need to keep the procedure separate from the prerequisites in order to make the procedure itself reusable. First, don’t use reuse techniques that make your content worse. It is better to duplicate than to mutilate. Second, if you choose the right reuse techniques, this should not be an issue. With the right approach, it should be possible to reuse a set of steps, insert them into a larger procedure, and have the steps be renumbered automatically.
Get prerequisites out of your docs
There are straightforward ways to handle all of the conditions that might lead you to including a prerequisites section in your instructions. You should never write prerequisite or preparation instructions that are separate from the main procedure.
The reason is very simple: people will start at Step 1.
Really, what else would we think they would do?
Your assignment:
- Search your docs for words like “preparation”, “prerequisites”, and “before you begin”.
- Move the contents of those sections into the procedures they belong to.
There are no prerequisites. Every procedure starts with Step 1.
Isn’t “don’t use reuse techniques” a little awkward? Or was that a demonstration of what not to do?
Well, it was not a case of reuse, so it wasn’t a demonstration of not [using | doing | employing | approaching] reuse correctly. It may have been an example of something else not to do. 🙂
What sorts of docs would be in / out of scope for the “assignment”?
(I don’t work with “user documentation” myself, so I’m thinking of looking at examples online and around the house.)
–Milan
Pretty much anything procedural would be in scope. Not to say you will find the problem in all things procedural, of course, but that is the place to look.
I guess the problem is that developers think in terms of prerequisites because it matches their design specifications. As a result this often gets duplicated into the user documentation when the writing department is not well presented in the organizational structure. I noticed this several times – an independent and somewhat ‘resolute’ writing
department actually does it’s work for the end user, whereas a hirarchically weak writing unit (perhaps just a few pitiful freelancers drowning in work) tend to write for the developers who need to approve their work.
Thanks for the comment, Robert. I think that is astute. The procedure-belongs-to-the-machine attitude is definitely one that makes sense from the developer’s perspective and if it is accepted uncritically by the writer, then the use of prerequisites to fill in the gap becomes the only choice.
We certainly need more resolute writers if tech comm is going to improve.
As to the assertion “People do not read instruction sheets through from the beginning”, would you put any qualifiers on that (e.g. types of users who are the exception, or circumstances under which people typically *do* read from the beginning)?
Milan: No. We’ve all been conditioned to ignore the beginning sections, whether that’s an explanation of the procedure, prerequisites, or the more common CYA text that tells you not to eat the air matress, dispose of it in a fire, or use it as a parachute. It’s rarely relevant, and often insultingly stupid (“Deleting a file: This will tell you how to delete a file. To delete a file, first…”). As Mark says, we skip that (because we assume we know it already) and go right to step 1.
If it’s an important enough procedure (“How to perform heart surgery”), the reader might be more attentive. But to Mark’s point, there’s nothing to gain by writing “Prerequisite: The patient should be sedated,” instead of constructing that as “Step 1: Sedate the patient.”
Well, clearly that statement has an element of hyperbole to it. Any absolute statement about human behavior usually does. It can become tedious to qualify all such statements, especially when everybody (<== hyperbole) recognizes the hyperbole for what it is.
But the hyperbole here does not affect the argument. Even if you can find one in twenty or one in ten people who do read the instruction sheet through from the beginning, that does not justify writing it as if everyone will. Most won't.
There is worse hyperbole in "That’s what I do. That’s what you do. That’s what everybody does." I'm surprised no one has yet responded to say, "That's not what I do." 9/10 people who do read instructions all the way through are tech writers. And yes, that's hyperbole. 🙂
Thanks Mark; hyperbole duly noted.
Thanks Neal.
As for “prerequisites”, I imagine that the sort of thing Mark has in mind might also appear under other headings. For example, in this:
https://commons.lbl.gov/download/attachments/76187871/EMRG-068%20(Rev.%203).pdf?version=2&modificationDate=1356113372044&api=v2
we see headings such as Application, Purpose, Scope, and Special Instructions before we get to Work Steps. Would this be a good candidate for the “assignment”?
That’s a kind of extra credit assignment, I think. Oy!
Ironically, my first steps usually read:
1. Ensure you have covered all the prerequisites for this task.
🙂
Thanks for the comment, Alex.
If there are prerequisites, that is certainly what step one should do.
It raises the question, though, of why not simply include the prerequisites right there in step 1 itself?
One answer to that question is that sometimes the so called “prerequisite” is something performed by another person or another process, and the first step of the current process is verify that that process has been completed correctly.
Here we are not dealing with prerequisite steps (to be performed by the current actor), but a prerequisite state of materials (that is the result of the correct performance of another actor). The current actor’s first step is verification of the work, not the work itself.
In this case, I would suggest that rather than saying
1. Ensure you have covered all the prerequisites for this task.
I would say,
1. Ensure that the widgets have been lubricated correctly.
This would then be followed by instructions for verifying correct lubrication, as opposed to instructions for lubricating (though a link to these instructions might not come amiss).
Hi Mark,
usually I use this step to cover all the stuff that needs to be done before that precise task. The machinery most of the time needs to be put into a special state, before performing an action. This prerequisite contains several other tasks that need to be done or avoided, have usually multiple starting states and often alternative routes.
Those are usually described in other specific parts of the manual, where those tasks are more basic use.
The problem here is, that those tasks often cascade and amass. This is why you can’t put it in the specific task you need them as prerequisite.
In a web context, you could simply use progressive disclosure to solve that (and place all the needed steps where you are currently) – but the web ain’t exactly the world of the machinery documentation, yet.
It is more of a compromise, than a proper solution. But it serves its purpose in the world of paper and PDF (some HMIs luckily provide PDF support today).
It is also a question of design and consistency of your content, if prerequisites are recognized or not. If they preceed every task and help the reader as a short overview (with references to the needed descriptions) or checklist, what has to be done before doing the task at hand, they _can_ even be an asset.
Think of them as the ingredients of a recipe. No recipe will start with:
1. Go out and buy 1 kg potatoes, 2 pounds of cabbage, 2 spoons of salt, 5 l of vinegar and some black pepper.
But this really comes down to layout and structure. The layout ensures, that the reader can’t miss the information. The structure ensures, that the information is ALWAYS presented at the same spot (right before the task steps) and in the same manner (preferably the same as the actual task steps).
The first step as I use it often, is then only the reassuring, that even those that skipped the prerequisites are reminded to check them first.
Thanks for the additional detail Alex.
I think the recipe is a great example. You are correct that a recipe does not start with:
1. Go out and buy 1 kg potatoes, 2 pounds of cabbage, 2 spoons of salt, 5 l of vinegar and some black pepper.
Rather, it starts with:
Ingredients:
1 kg potatoes
2 pounds of cabbage
2 spoons of salt
5 l of vinegar
black pepper
That is, it starts with a list of materials or inputs.
I think there is a big difference between prerequisite steps (which is what I was ranting about in this post) and a list of inputs. I’m not advocating including the entire list of inputs in the first step. Preceding the procedure with a list of inputs is a pattern that is well established and well recognized and will not likely cause confusion for most readers.
Even if they skip the list of inputs, the inputs will be referred to in the steps, so the inputs won’t simply be forgotten. (Even so, it is often prudent to tell people to check they have all the inputs as the first step.)
You are certainly right about the limits that paper imposes on our ability to effectively represent relationships between objects and processes in the real world. Since we cannot reduce all these relationships to a single linear structure, we have to use references from one piece of content to another. On paper, all such references are either forward or back, and each has a specific distance forward or back (like trying to locate data on a computer tape on an old mainframe).
The further the reference, the more costly it is, so we developed numerous conventions for creating small caches of content nearer the place where they would be wanted. The list of prerequisites is one of those conventions.
Hypertext gives you a completely different mechanism for expressing and traversing content. Relationships can be in any direction, and they are all the same distance (effectively, zero). We are a long way from fully adapting our conventions to the ability of this medium to express relationships.
Thanks for the great article, Mark. I think your point of view here merits a great deal of attention.
On the other hand, I can’t quite agree with your assertion concerning distance in references for hypertext. In fact, by virtue of the way that most people use browsers, the distance could equally be defined as infinite = by the time I’ve hit a couple of hyperlinks, to follow references, it may be arbitrarily difficult to find the way back to the original text …
Thanks for the comment, Adam.
You raise an interesting point. Hypertext links are one way, so if A links to B and not vice-versa, B is a lot closer to A than A is to B. A hyperlink, per se, is zero distance, but that does not mean that every page on the web is zero distance from every other.
Of course, your browser does provide a back button and a history of pages visited, so it is not normally that difficult to get back to where you were.
In a coherent information set, though, a coherent link strategy should strive to make sure that links are provided that take the reader to semantically related content, which should mean getting back is as easy as getting there.
These points are especially true when you consider the safety requirements of some procedures…duoble-checking as Step 1 can save lives and/or prevent bad things from happening.
I especially love your line”It is better to duplicate than to mutilate”. 🙂
Thanks Karen. There are times when the universe drops a gem in your hand, and that’s how I felt when that line popped into my head. I’m thinking of having buttons made.
Pingback: Tech Writer This Week for July 17, 2014 | TechWhirl
I would argue that the air mattress should have shipped with the valve on the other end closed. Maybe that makes it harder to fold up in the packaging, but it’s very frustrating to fail at using a product that should be simple.
Regarding prerequisites, I start several long procedures out with heading called “Prerequisites” and then have procedures within that section. It worked during testing, but we’ll see what happens when it gets into the field.
Thanks for the reply, Justin.
Definitely agree the air mattress design was bad. But the instructions could have rescued it and they didn’t.
thanks for your thoughts on this, Mark. your explanation is very logical, and I like your point about starting at step 1. I hadn’t really considered this before, but this seems very clear to me now. Why didn’t I think of this before…I like the idea a lot, it makes sense. Joanne
Really can’t agree. There are things you might need to do BEFORE you start any procedure. A recipe lists the ingredients BEFORE you get to the steps for using the ingredients. A list of ingredients is not step 1.
Prerequisites should not be a list of steps. But things that need to be done ahead of time in order to complete the procedure. The confusion here is thinking that prerequisites are a list of steps.
Thanks for the comment, Joan.
If “things you might need to do” and “things that need to be done ahead of time” are not steps, what are steps, if not things that need to be done? What is the difference between “ahead of time” and “first”.
But the point this is not to debate whether or not there are different classes of things that need to be done in some abstract taxonomy of activities. It is to point out that your typical reader, anxious to get stuff done, ignores all the bumpf before “Step 1” and starts there. You can argue all you like about the distinction between prerequisites and steps, but it makes no difference if all the reader reads are the steps. If all the reader reads are the steps, everything needs to be in the steps. It is really as simple as that.