Writing User Manuals from the Middle Out

You need to write the user guide for a complex product. There must be a dozens of functions and hundreds of tasks that can be performed with the product. Where do you begin? How to start writing? Conventional wisdom says: start at the beginning with an introduction to the product, and work your way through each function or task in the order the customer will use them. Don't! Here's a tip I learned the hard way after my ninth or tenth year tech writing: start in the middle, and work your way outward.

This article presents a method of writing user documentation that you may find easier and more effective than starting at "Chapter 1:"

1. Start by writing procedures for each task or menu option. This is the "middle" of the document, and results in a collection of subsections.

2. Then, add material just before and after each procedure. This is working "from the middle out." The result is a collection of sections.

3. Organize the sections into chapters, and add more material to the beginning and end of each chapter.

4. Finally, organize the chapters into a manual.

I have found that this method of writing user manuals from the middle out saves time, and yields more accurate and useable documentation.

Why Not Start at the Beginning?

When you begin your manual with an introduction to the product, you also begin your research with an introduction to the product. Typically, you ask the Marketing or Sales department to describe how the product will help the user: "What will users do with it?" You ask Development or Engineering to describe the product's structure: "What is it?" You experiment with the product long enough to determine how it's used: "How does the user use it?" Then, you write your introduction. Which will probably contain inaccuracies and be less useful than it could be, for three reasons:

First, you are attempting to describe the purpose of the product ("What will users do with it?") before you have completely experienced using the product. By asking others what the product does, you are only discovering what they believe the product should do. You must first use almost every function of the product to determine what it really does. Remember, the manual is for users and should be written from a user's point of view. You can better convey the purpose and advantages of a product to a user when you have completely experienced the product from the user's point of view. This is why, in the middle-out method, you write the introduction last.

Second, you are describing the structure of the product ("What is it?") before you have experienced how the pieces of the product work together. Describing what the modules of a software application are is not nearly as useful to the user as describing what those modules do, and how they work together. You can best determine what they do and how they work together by experience.

Third, you usually develop the outline for your manual at this stage. Remember that the outline will determine the order in which you present the product's functions and tasks. And, you have not yet performed all of the product's functions and tasks. After you have experienced a complete cycle of using the product, you will be qualified to determine the order in which to present the procedures for using the product. At this point, determining the order for these procedures is guesswork.

In sum, when you begin writing a manual at Chapter 1, the manual becomes a diary of your learning curve. The first sectioins tend to be either ambiguous or self-obvious. They become ambiguous when you are conscientious enough to attempt to state something meaningful about the product, when have yet to gain real experience with the product. They become self-obvious when you attempt to state only those facts of which you are sure. Because you have little more experience than the reader, those facts will tend to be self-obvious. Starting in the middle and working outward avoids these problems.

How to Do It

To create user documentation from the inside out, follow the suggested steps below.

Write the Sections

Following the steps below will result in a collection of sections. Later, you will organize these sections into chapters, and then a manual.

1. Write the directions for each task or function.

Let's assume one of the tasks the user performs with the product is, "Create a new record." Write directions for this task. Don't worry about:

• The purpose of the task (Why create a new record).

• Where it fits into the big picture (When to create a new record).

• What the user must do or know before performing the task (Prerequisites for creating a new record).

The only thing you are writing is how to perform the task at hand.

Repeat this for each task or function the user can perform with the product. When you finish, you will have a collection of directions for performing all possible tasks or functions with the product. Label this paragraph "Directions."

2. Add prerequsites in front of each task.

Add a paragraph of prerequisites in front of each task. In our example, the prerequisite might be that the product must be in a particular mode before creating a new record. This paragraph should tell the user only and exactly what conditions must exist before the procedure can be carried out. Label this paragraph "Prerequisites."

3. Add results after each task.

A results paragraph states what the user should see to confirm that the task was successful. It also states what has changed as a result of the task. Label this paragraph "Results."

4. Add background knowledge before the prerequisites.

Examine each task and determine exactly what the user must know to successfully perform that task. Put exactly and only the background knowledge the user must know for a task immediately before the prerequisites for that task.

If several tasks require the same background knowledge, you should probably organize them into a chapter or section and place the background knowledge only once at the beginning of that chapter or section.

5. Add next steps after the results.

State what user must, should, or can do next.

After following the five steps above, you have a collection of procedures. Each procedure comprises a section, consisting of:

• Background information

• Prerequisites

• Directions

• Results

• Next steps

Organize the Sections into Chapters

Only now that you have performed every task possible with the product, and determined the prerequisites and results of each task, can you see how they fit together into the overall process of using the product. Now you are ready to determine the proper sequence for performing the tasks, the purpose of each task.

Organize the sections (procedures) into logical groups. You may organize the procedures in the order in which the user is most likely to perform them. Or, you may group procedures with similar functions together. Whatever scheme you choose, each group of sections becomes a chapter.

Now examine the procedures in each chapter and ask, is there any information that the user must know to perform these procedures? At the beginning of each chapter, add exactly and only the information the user must know to perform the procedures in that chapter. Label this section "Introduction."

Determine the Purpose of Each Procedure

Good user documentation doesn't tell the user only how to perform a procedure. It also tells the user when. Now that you have experienced and organized all of the tasks for the product, you are qualified to determine when it is appropriate to perform each procedure. A "When this... Do this..." table is one effective way of presenting this information. You can place this "When..." information in:

The introduction to the manual. You would probably include "When..." information for all of the procedures here. This is usually the easiest place for the user to find the information.

The introduction to each chapter. You would probably include "When..." information for only the procedures in the chapter here.

Each section. You would probably include "When..." information for only the procedure in the section here. This is usually the most difficult place for the user to find the information.

Finally: Write Chapter 1

Now, look at the whole manual. Is there any background info that a user must know before using any of the procedures in the whole manual? Write it down. Call it "Chapter 1: Introduction."

Assemble the chapters, generate a table of contents, and you've got yourself a manual!