We're Ready To Write the Documentation

We’re Ready to Write the Documentation

All of my articles have focused on the many facets of planning user documentation. Now that we know about our audience, have thought about our page layout, and decided who will write the manual, we can talk about issues related to the actual writing.

In writing the manual, you should follow some general steps that include:

writing an outline

2. gathering information

3. creating a prototype

4. obtaining comments on and approval of the prototype

5. drafting the remainder of the manual

6. reviewing the whole manual

7. making revisions or corrections

8. finalizing the text and layout

You do not necessarily perform these steps in this exact order. You may find that some of these processes are iterative. That is, as you draft the outline, you will need to gather enough information to determine the topics you need to cover. You will most likely need to gather more information before you begin to write each section. You may also have more than one review cycle.

Based upon the results of your audience analysis and the decisions about how to structure your documentation, you are ready to draft an outline. Remember that your outline will become your road map to writing the manual. You want to be sure that if you decided that a reference manual is what your users need, that your outline reflects that decision.

For a reference manual, you will probably need to list each of the main system functions or features. These will be your main topics. Most reference manuals organize the functions in alphabetical order and describe how to use each one.

Your outline should also include each of the subsections you will need for each feature or function. Some of these subtopics may be similar for each topic. For example, you may have the following sections for every topic: Overview, Tips, and Troubleshooting. You will also need unique subtopics that explain how to use the feature. You can name these subtopics with phrases that start with a verb. For example, "Using Table-Ease to Create a Table," or "Formatting Text with Easy-Format" could be subtopics for a word processing software package.

When you’ve listed all the functions, tasks, and the subtopics you need, you have your outline. Of course, you will most likely want some additional sections in the front and back of your manual. These sections typically include a table of contents, a getting started section that explains how to load and set up the software, an introduction, an index, and possibly a glossary, and a list of figures or tables. You should add these to your outline too, so you cannot forget them in the heat of your writing efforts.

If you are writing a task-oriented manual, that is, one that explains how to perform entire functions that a user needs to perform, you will need to take a different approach with your outline. Actual users will be the best source of information. You should ask them to tell you the main tasks that they perform with the software. Those main tasks become the main topics in your outline.

You will probably find that each task has a number of steps that the user performs. These steps become the subtopics. For example, if someone is creating a purchase order, the steps may be getting the purchase order number, entering customer information, and calculating the total. Those would also be the titles of the subtopics in your outline.

Once you’ve completed the outline, you should submit it to whomever must approve the manual. You may have a team consisting of the project manager, lead programmer, and others who should review and approve the outline. The review team will help to ensure that you have included all of the topics you need and that you have organized the manual in a way that will permit users to find what they need.

You may need to talk with members of the review team to discuss why you’ve organized the information the way you have. You also need to be open to their ideas and suggestions.

After the review and revision process, your outline is complete. Now you can start to gather information for the manual. Your information may come from any number of sources including old manuals, specifications and other planning documents, subject matter experts, etc.

You should also have access to the most current version of the software. That way, as you write, you can try things out. You may find that some of the information you have does not accurately reflect what the software does. If you find inconsistencies, you should call them to the attention of the project manager.

You may also find that you have suggestions for changes or improvements. You should express those ideas as well. The writer often has a user perspective that the programmers and others close to the project have lost.

When you are ready to write, you should draft one entire function or task as a prototype. I'll talk more about the prototype and other writing issues in my next article.