Writing the First Draft of Your Manual

Writing the First Draft of Your Manual

Now that you have the information you need, you can begin writing your manual. Notice that I did not say, "all the information" you need. You will run into new questions and issues as you write your first draft. That is normal.

As you write your draft, be sure to work from your approved outline and prototype. They will help you stay on track. Use the information you gathered as your primary source.

When you are writing the draft, your primary goal is to put on paper (or in your word processing file) the main points that you need to cover. You will have to go back and edit. Don’t expect to write the first draft perfectly. No one does. Once you get started, you’ll find that the words will flow and you’ll build momentum. Use this momentum to continue drafting entire sections of your manual.

If you find that you have questions, write them down. Don’t try to get the answer to every question as it arises. If you interrupt the flow to resolve every question that comes up, you will find it hard to pick up where you left off. Unless the question is critical to the entire section you are writing, jot down the question and ask it later. Waiting to ask questions also helps you avoid calling your subject matter experts every five minutes. They wouldn’t appreciate such frequent calls. Also, you may find the answers to some of your questions as you review the information you have.

For a product that is under development, you may have to leave gaps in your writing for features or functions that are not yet developed. Be sure that you note where you need to add information. You’ll need to follow up with the developers to get the latest feature descriptions. In a situation like this, you will also need to double-check all of your facts. Since the product is under development, features that you already know about can also change. Try to get the latest version of the product to use whenever a new version is available for testing.

In addition to the writing tips I discussed in the previous article, here are few more suggestions to keep in mind as you write:

Graphics, Warnings, Tips During your planning, you should have decided what graphics, warnings, tips, or other special notes to use. As you write, insert a placeholder where you want to insert a graphic. That way you’ll remember and you can refer to the graphic in your text. When I write I just add "[Insert screen shot of the ABC screen]." That way I cannot forget to insert the graphic and the notes in brackets are easy to spot. For tips and warnings, either insert a similar note where they belong, or write the text for them when you are writing the appropriate section.

Glossary/Index If you plan to include a glossary or index, you should create a list for each as you write. Add to your lists the terms that you think should be in the glossary and any topics you think should be in the index. These lists will help you when it comes time to create the glossary and index. I know, you’re thinking that your word processing or desktop publishing software manuals say that they can produce your index automatically. Well, be skeptical. The tools included in your software will help you create your index, but if you want good index that your audience can use, you will need to decide what topics to include. Your lists will make it easier when you are ready to create the index.

Short sentences You generally want write short sentences. However, even in a manual, you need to vary your sentence length periodically. Five or six very short sentences in a row sound choppy. When you write longer sentences, be sure to keep them clear and concise.

Conversational style You want to write in a conversational style. The words you use and your sentence structure should be similar to the way you speak. We often fall into the habit of writing in a style that is too formal and does not sound natural. Writing is normally more formal than the spoken word, but your writing should still be conversational, not stilted and stuffy.

Necessary information You want to include the information that your audience needs to know, but you have to think about whether you are adding information that is not necessary. Unnecessary descriptions and background just clutter up the manual. Always keep your audience in mind as you write.

When writing your draft, cover each topic as completely as possible. You can then concentrate on your writing style when you begin to edit. In my next article, we’ll talk about editing and proofreading your draft.