How to organize a Product Manual

There's a basic formula for organizing product documentation. Some people reject formulas, but if you remember, the goal is to put the users first and to keep it simple, and keeping it simple is meant to help put the users first. By basing your documentation around this formula as much as possible, you'll make things easier for your readers.

Product documentation is built on three types of information:

• Concepts

• Tasks

• Reference material

By organizing every part of a manual with these three building blocks in mind, you help users:

• Scan for the information they need

• Make sense of complicated topics

• Quickly get in and out of the doc so they can get back to work

• Create a kind of inverted funnel of information, where you present the basics for understanding a task, then more info as needed

This formula works at every level of a product guide, from the overall outline of the guide down to a paragraph. Really, when you think about it, it's not that different from the old composition rule you learned in school, where each paragraph begins with a topic sentence, and then you add more detail to flesh out the thought.

At the most basic book level, much of the basic conceptual info is at the front of the book. Then, most of the rest of the book consists of tasks, and there are appendixes at the back containing reference material.

For a chapter, you begin with a little bit of conceptual info, which leads in to tasks. If there is any reference material in the chapter, it is often found at the end.

Likewise, each topic begins with a concept, before moving on to a task. In a topic, reference material is usually presented where it is most needed, or it might be at the end.

And, in task-based documentation (which good product doc should be), each topic is built around a task. A task is normally presented as a procedure. A procedure is a series of steps. And each step is organized as the thing you do, followed by an explanation of what you're doing and why. If there are choices to be made, then the choices are presented next. That's pretty much the concept > task > reference model turned around slightly to task > concept > reference. Even though the order had changed, though, the information types remain distinct.

For example, a step might be something like:

4. Choose the option that best applies from the Options menu.

   The option you choose determines how the program will send alerts when new data is available.

   The possible options include:

   * E-mail

   * RSS feed

   * Instant message

To help your users find their information, you need to keep each of these building blocks separate. In other words, don't put steps in a concept section. Don't mix concepts into the actual step part of a procedure. Don't include steps in a table that defines terms or describes features.

You also need to pay attention to your headings. The headings you use for each section signal to the reader the type of information the section contains. So, for example, if you have a heading like “Printing a Document,” that signals to the reader that the section contains instructions on how to print. If the section only contains conceptual info about printing, the user will be frustrated because they didn't find what they expected. If it's conceptual, you could call the section “Understanding Printing” or “About Printing,” or whatever the company style dictates for conceptual information. Just don't give it a task-based heading if it's not a task.

Likewise, don't call a section "Understanding Printing," and then include a procedure that shows how to print. When looking at the Table of Contents, the user will see "Understanding Printing," figure he already understands printing, and completely miss the steps.

Headings are some of the most important breadcrumbs that help readers find information. Make sure they reflect the type of information the section contains and accurately describe the section contents.

Of course, your “Printing a Document” section could contain both concepts and a task. If it does, the two parts should be distinct. Start with a paragraph or two that explains the conceptual information, as concisely as possible. Remember, the conceptual info doesn't have to include absolutely everything there is to know, just what the user needs to know in order to perform the task.

Once you've introduced the task with the necessary concepts, then you move in to the procedure. You can still provide conceptual info within a procedure where it is needed to complete a specific step, as in the example above, but keep it brief, focused, and in the right place. The right place is almost never in the actual step, but in a paragraph following the step. This keeps the task and concept separate and makes the procedure easy to scan. If the user doesn't need the conceptual info, they can perform the step and move on to the next one without getting bogged down in details they don't need.

If you pay attention to the three basic information types and chunk the content of your documentation according to these types, your users can quickly scan the document for the information they need. If they know the concepts but don't remember the procedure, they can skip to the task. If the procedure's not a problem but they don't understand a concept, they can easily find the concepts and ignore the rest. And, if they just need to know what something is or what it means, they can refer to the reference info. The info they don't need is out of the way, so they don't waste time picking the bits they want out of a mixed up doc section.