Drafting the Manual Prototype

After you have put together the outline for your manual, you are ready to draft a prototype section. Why create a prototype? There are a variety of reasons.

First, you can test your page design, outline, headings, etc. in a small document. That way, if you find that you need to revise your formatting or the organization of the content, you have found out early in the writing process.

Second, the prototype gives you something to show to your management (or whoever must approve the documentation) and users to ensure that the manual will meet their needs.

Third, you will find it easier to start with one representative section. The writing task will seem less formidable when you begin small.

As you write the prototype, you should keep in mind several basic rules of thumb.

Use the active voice. The active voice makes your writing more interesting and should dominate your writing. In case your grammar is rusty, in active voice, the subject of the sentence performs the action of the verb. For example, "You can install the software on your c: drive or on a network drive." The passive voice often has the word "by" in it. For example, "The software can be installed on the c: drive or a on a network drive by the user." Notice that the passive voice example takes more words to express the same idea as the active voice example.

Address the system user as "you." When you write your instructions this way, they seem more friendly and understandable. (See how I used "you" in the previous sentence. Notice how I do that throughout my articles.)

Write steps the user must follow in numbered lists. You should set off the numbered lists, usually by indenting, to make them stand out.

Write the steps with verbs in the command form. (You use the command form of the verb without a subject. The subject of the command, you, is implied.) For example, "Click the OK button." When writing steps the user must follow, make absolutely sure that what you write is exactly what the user should do, in the exact order.

Choose your words carefully. You should define any terms that might be unfamiliar to your reader. Remember how you investigated the audience for your documentation? Keep that audience definition in mind as you write. Try to use simple, commonly known words whenever possible. Skip technical terms and jargon if they are not necessary.

Write concisely. Use the fewest possible words to explain concepts. This is especially important when writing steps. The user does not want to wade through three lines of text to figure out that the next step is to click on the OK button. Of course, don’t be so stingy with explanations that your readers will not understand what they need to know.

Be consistent. This concept is extremely important. We have many synonyms in English. Once you start using a term to refer to a specific function, keep using it. We are not writing the great American novel here. We don’t need to vary our terms to make the writing more interesting. In fact, varying terms will make your manual confusing. If you call the first menu someone sees on the system, the Main Menu, always call it that. Don’t refer to it as the First Menu later in the manual. You will only confuse your users.

Highlight critical information. As you designed your document, you should have decided how to handle warnings and other information that your users must know. You should set off such information in a box or in bold type. Sometimes manuals use a symbol next to the text to make it stand out.

In addition to following these writing tips, you should be sure that your prototype includes all or nearly all of the different types of information and formatting elements that you will use in the manual. If you expect to use tables to present information, or screen shots from the software, you should include them in the prototype. That way you can see how to incorporate them into the text and your reviewers will see something that is representative of the entire manual.

Now that you have drafted the prototype, you are ready to send it to the reviewers. We’ll talk more about the review process in my next article.