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.
Posts
No comments:
Post a Comment