The point of an Overview chapter

Let's look a little closer at one part of a manual that often causes technical writers difficulty, the introduction or overview chapter at the beginning of a manual.

It is tempting to throw as much information as possible into that overview. Many writers succumb to the temptation, explaining every conceptual detail in the overview. On the surface, that might seem like a good idea, and it appears to follow my model of putting the concepts up front.

The thing is, though, that you have to put the user first, which means you need to remember how the user is likely to use the doc. In most cases, users don't want to actually read the manual. They want to use it when they need help completing a task, usually after they ask a couple of coworkers for help first. That means you need to put the information where the users need it. It also means large blocks of dense text are going to be ignored.

The purpose of the overview is to orient users to the product, not to teach them everything they need to know. If you throw too much at them up front, they'll get confused. That is, they'll get confused if they bother to read that big ol' block of text.

Let's say we are working on a manual for a product that tracks tasks. We've divided the manual into the following parts:

• Overview

• Setup and Configuration

• Creating Tasks

• Viewing Tasks

• Changing Task Status

• Running Task Reports

This is a pretty straight forward, task-based organization, with a conceptual overview up front. The overview should contain the most basic information about everything you can do. That probably means only a sentence or two about each major concept, with a cross-reference to where to look for more information.

The first thing the overview in this guide should do is answer whether this is the product that will help you do your job. Then, it should briefly explain the features and their purpose.

When discussing reports, our example introduction would explain that you can run reports and the purpose of those reports, then point you to the reports chapter where you can find more detail if you need it. The reports chapter would then begin with a concept topic that tells you a little more and explains the kinds of reports that are available. Then it goes into the tasks, with a more specific conceptual info at the top of each task section, if needed.

The point is, an overview is not the place to try to teach everything about everything. People learn by doing, so putting the details closer to the tasks will make them easier to remember. The details make more sense in context.

By placing the information in the right places, it is also easier to find. Using our task software as an example, if I need to know how to mark a task complete, I'll look at the table of contents (or maybe the index, if there is one). I'll go to “Changing Task Status,” expecting to find everything I need to know about task status, including how to change the status to complete. I'm not likely to go to the overview.

Everything in the manual should be designed to point users toward the information they want to find. Whether it's the overall outline of the manual, the wording of chapter titles and headings, or an organized structure of the information itself, everything is a bread crumb that leads a user toward a solution and gets him back to work. Large blocks of text don't usually do that.

The primary purpose of the overview, like the primary purpose of the doc, is help users do their jobs. Educating the user is a secondary purpose related to the first. In most cases, users don't need or want to know everything. They want to know how to do what they need to do.

The overview, then, is a key part of this strategy. It helps to orient the user to the software, and helps to point toward essential tasks. It's a view from a distance, where main features are visible, but the details are not. It's a part of the inverted cone of information, near the point. If your overview becomes the widest part of the cone, then there is no point. If it's pointless, you'll lose your audience.

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.

Keep It Simple

Everything I write on this blog will be based on two principles:

• Keep it simple
• Put the user first

It's easy to argue that you're not putting the user first if you don't keep your doc simple. That's why I chose simplicity as the topic for this first post.

One of the first things I was taught as a fledgling technical editor was that I needed to forget about all of that writing stuff I learned in college. There's a place for a nice complex sentence, but that place is not in tech writing. Same goes for metaphors and similes and many other hallmarks of good academic writing.

My first boss said that the idea is to write around an eighth grade level. I'd say that's about right. You want to use simple words and sentences that are easy to parse and do not contain multiple ideas.

The sole purpose of product documentation is to help people find the information they need so they can get back to their job or their game or whatever it is you're helping them do. To help them, you want to make everything easy for them.

Unlike academic writing or literary fiction, technical writing is not the place to show off your writing skills. Actually, you want to be completely invisible. The only thing that matters is the information you want to convey, and that should be presented in an easy-to-navigate manner. The object is to help your reader get in and out of the document as quickly as possible.

A user-centered, task-based approach works best. In everything you do, think of what you're trying to help the user achieve, and then make that task as simple as you possibly can.



----------------
Now playing: The Moody Blues - This Morning
via FoxyTunes

Welcome

Welcome!

I've been planning this blog for a while. I hope it will be of interest and use to people who are interested in technical writing, either because it's what they do for a living or because they're thinking of going down that road.

Some of the topics I plan to cover in the near future will focus on creating user-centered documentation. Things like focusing on tasks rather than on the UI and helping the reader find information quickly.

So, stop in and take a look. And if you find this blog useful, leave a comment to encourage me.

Speaking of comments, respectful disagreements are definitely welcome. If you disagree with something I write or have better ideas, please comment. Good discussions will help everybody learn.



----------------
Now playing: The Zombies - I Don't Want to Know
via FoxyTunes