Siechert & Wood Professional Documentation
HELPFUL
INFORMATION

How to Review
a Document


Siechert & Wood home

Contact Siechert & Wood, Inc.

1ptrans.gif (807 bytes)

 

As a marketing manager you are called on from time to time to review documentation for your products. Use this summary as a reminder of what to look for as you review.

Before you Begin

Before you begin the review, you should answer the following questions.

At what stage is the document?

If it is a first draft, you should check for completeness, appropriateness, organization, etc.

If it is a Final draft you should only be making minor changes, correcting technical errors, and adding late-breaking information.

Who is the audience?

This question should have been answered at the start of the project, so now is the time to remind yourself who the target audience is.

What are your goals for the document?

Before you start the review, remind yourself of the goals of the document. Some typical goals are:

  • To reduce support costs
  • To be "better" than the competition
  • To promote a particular image
What is the scope of the document?

Is the document a "getting started" booklet or an exhaustive reference manual? Consider this when you look at what’s missing from the document.

What are your standards?

Review your documentation standards. If your organization does not have an applicable standards document, there are several published style guides available:

If a style sheet was created for this document, review it.

The Review Process

As you review the document, answer these questions:

Does it meet your marketing objectives?

The document should meet the goals you set. Its description of the product should be consistent with your marketing materials.

Is it technically correct?

You probably know your product better than anyone else. the document should faithfully describe the features and operation.

Now is the time to be sure that last-minute product changes are reflected in the document.

Are the trademark and copyright notices complete and accurate?

Check that all your trademarks are included in the trademark notice, which is probably on the back of the title page. Be sure your organization’s name is correct in the copyright notice.

TIP: There is an easy way to check many companies’ trademarks. Click the "copyright" or "legal" link on their home page. Many companies now include a list of their trademarks on their web sites.

Is there anything missing?

Be sure that the document covers the defined scope. Be sure that the authors have overlooked nothing.

Is the writing in active voice? Is it concise?

Use the active voice. It’s clearer and more concise. Here’s an example.

Good Bad
1. Click OK. The next dialog appears. 1. You should use the left mouse button to click on the OK button. When you click, the next dialog will be displayed.
Is the writing style consistent?

It’s disconcerting and confusing to find several writing styles in the same document. While this can be a problem with documents that are written by multiple authors, it’s the editor’s job to meld the styles.

Are there spelling, grammar, or punctuation errors?

You should not have to check spelling, grammar, and punctuation. If you are finding this kind of problem (except in very early drafts) you should be thinking about changing writers.

Communicating Changes

It’s important that you communicate your changes clearly to the people producing the document.

Do

Use a pen of a contrasting (and unique) color. Identify yourself on the first page with that pen. Include your phone number and email address so that questions can get answered quickly.

If you have large additions, type them into a separate file (use one file for all your additions) and indicate where they go on the draft as "insert A" and so on. Be sure to identify them in the additions file, too.

Use standard proofreader’s marks to communicate your changes. They provide a concise way of indicating what you want done. See the illustration of proofreader’s marks below.

Return the original marked-up draft. You can keep a copy. It’s important that the production people have the contrasting colors so that they can spot every change.

Don’t

Don’t make comments such as "This is wrong" or "Missing a step." You must provide the correction. If the writer had known what's correct, there wouldn't have been an error.  (If you don’t know what is correct, identify the person who does on the draft.)

1998 Siechert & Wood, Inc. All rights reserved.