Writing Procedures

Step by Step

Some thoughts on writing steps for documentation.

How many times have you read a manual that had procedures that were written something like this:

1. Click the Install icon.
2. The splash screen appears.
3. Click OK to begin the installation.
4. The installation begins. A progress indicator appears.
5. Wait until the installation is complete.
6. Your computer should be restarted before you run the software.

Do you see the problem? Steps 2, 4, and 6 are not actually instructions. The technical writer has confused the various stages of operating the product with the actual steps that the user must take.

Or how about this one:

1. Click the Install icon.
2. When the splash screen appears, click OK to begin the installation.
3. When the installation has finished, your computer should be restarted.

This variation might seem a bit better at first glance, since it uses fewer steps to accomplish the same thing, but it has a whopping big problem: The actual instructions in steps 2 and 3 are hidden behind conditional phrases, and are buried at the end of the sentences. This is poor structure.

Confused writing is a side effect of trying to document confusing products. When software configuration develops multiple branching paths, the documentation often gets as confusing as the product. And the customer suffers.

The technical writer should develop a formula for procedure writing that helps make sense of the product being documented, while at the same time help the user understand the product better.

How about this:

1. Run the install program.

   Click the Install icon on your desktop. A splash screen appears.

2. Start the installation.

   Click OK to begin installing the product. A progress indicator shows you how long this will take.

3. Restart your computer.

   You must restart your computer before using the product. Select Apple → Restart….

(I've provided a more complex and realistic example to better show how this approach can work.)

This set of steps is certainly better written, but there's more going on here than just clear writing. This approach has several different things going for it.

• First, note that each step begins with a verb in the active voice. This should be an ironclad rule, because it gives users a firm direction.
• Second, note that the first sentence of each step is boldfaced. This is a summary line that can be used to outline potentially more complex operations. There is an old adage in broadcast journalism: Tell 'em where they are, tell 'em where they've been, and tell 'em where they're going.
• Third, by eliminating any conditional phrasing from the summary line, it allows the writer more freedom to explain branching steps without having to resort to awkward phrasing.
• Fourth, the summary line helps two kinds of users: neophytes, who need as much guidance as possible; and experts, who need just a top-level outline of the procedure.
• Fifth, this much more formalized structure helps the writer understand the procedure better.

This "summary-line" approach can work for almost any user-driven product.