Reviewing Your Manual Prototype

In the last two articles, I talked about creating an outline for your documentation and drafting a prototype. Please remember that my articles apply to any type of documentation, whether you are writing a procedure manual, personnel handbook, or equipment maintenance manual. The basic planning and writing steps are the same.

Once you have drafted your prototype, you should start the review process. You may work for a company or in a department that has already defined when and how you submit documents for review and who will review them. In other cases, you may have to set up your own review process.

If you are an outside consultant, you should ask about your client’s review process. If your client has not defined one, you should work with your primary contact person to decide how best to handle the review. Review processes will differ depending on the company, your relationship with the company (whether you’re an employee or a contractor), and the type of document you are producing.

You want to be sure that your management or client likes the prototype and approves the following four elements:

Page design and layout
Organization of the information
Writing style
Accuracy

First, you want to be sure that your page design meets the objectives of your management or your client. Remember that your page design must take into account not only what looks good and is easy to read, but also how you plan to reproduce the document (I discussed these topics in my More Documentation Planning Issues? Yes! article).

Second, be sure that your approach to the material meets with the approval of your management or your client. You need to ensure that the organization and presentation of the information is logical and easy to understand.

Third, ensure that the writing style fits the needs of the manual’s audience. You don’t want to use jargon, long sentences, or the passive voice. I included some general writing tips in my Drafting the Manual Prototype article that will help you.

Fourth, you want to be sure that the information in the prototype is accurate and complete. Although you will have further technical reviews, you should review for accuracy from the start.

Before you send the prototype to the reviewers, read it again yourself. As you read, consider the issues outlined above. Be critical and rewrite any sections that do not fit your audience or that contain long, difficult sentences.

Now you need to think about who should review the prototype. Again, this depends on the type of document you are writing and the company you working for. In general, you should consider including the following people in the review cycle:

Project manager
Project leader (if different from the project manager)
Technical expert (for example, the lead programmer)
Product manager (for a commercial product)
Writer or editor (from your own or another department)
Manager or officer who heads the organization developing the project

You will probably want to discuss this with the project manager or whoever your primary contact is in the development group. Your main goal is to ensure that the prototype is thoroughly reviewed so that no one will be surprised when they see the final document.

You may find it valuable to include a high level manager or officer (the last person on my list above) in the prototype review. You may not want to include this person in subsequent reviews of the document, but getting buy-in at a high level for the prototype is a good idea. This will avoid problems later.

You also need to decide how you want to conduct the review. You have a few options which include:

Holding a meeting with all the reviewers at the same time.
Holding a series of meetings with each reviewer individually.
Requesting written comments on individual copies of the document.
Requesting written comments on a single copy that is sent round-robin (each reviewer writes comments in a different color).

For the first two options, you need to send the reviewers a copy of the document before the meeting(s). The advantage of the fourth option is that each reviewer sees the comments of the previous reviewers. This can save everyone time by eliminating duplicate comments, but the total review process will take longer.

No matter which option you pursue, you will need to clearly explain to the reviewers what you want them to do, how you want it done, and when the information is due back to you.

You may want different reviewers to look at different elements of the prototype. You may ask some to comment only on the accuracy and others to comment only on the writing style. You will need to clearly explain to the reviewers which elements they need to examine and which they can ignore.

Getting the cooperation of your reviewers can be the most difficult task when you write a manual. Be prepared to follow up with your reviewers and develop an alternative plan, if possible, in case your reviewers don’t respond.