Review Checklist for Technical Documents

Making a list, checking it twice…

How do you review your technical documents? You just don’t eyeball them, right?

Before you send your shiny new user guide into the wild, use the following checklist to review your technical documents:

Title

Is the title consistent across all documents? Note lower, mixed, and upper case combinations

Product name

Is the name of products consistent?

Branding

Does the document adhere to the company style guide?

Strapline

Is the strapline consistent?

Logo

Is the same logo used on all documents?

Cover sheet

Check legacy documents or documents created with a rogue template

Version

Is the same version number used on all documents?

File Properties

If writers use File, Save As to create a new document, the ‘old’ file properties must be updated

Table of Contents

Has it been updated? Have rogue sections crept in?

Language

Are UK and US English used in the same document?

Should

Don’t write what might happen next. Explain what to do right now when you’re performing the procedure.

Instead of:

The command should be run if a new product is installed.

Write:

If this product is installed, run this command.

Will

Don’t write what will happen, say what is happening now.

Incorrect

This will create the following files in the Bin subdirectory.

Correct

This creates the following files in the Bin subdirectory:

Start with Verbs

Incorrect

The folder located on the D: drive should be copied from the server.

Correct

Copy the folder located on the D: drive from the server

Screenshots

Add a caption and explain what’s happening in the screenshot.

Don’t assume the reader understands what’s happening in the screenshot.

Within v in

Don’t say the chapters within the document.

Within specifies a time frame, for example, within 3 days.

Prerequisites

List prerequisites in the correct order.

If you have to install prerequisites in a specific order, use a numbered list. Add warnings, cautions, and recommendations.

Upgrade

In the Upgrade section describe:

• New install — how to install from scratch, a clean install.
• Upgrade — how to upgrade an existing installation.
• Uninstall — how to remove the application from your system. Include any recommendations or warning before they start.

Repeated phrases

For example, if you say that you need to perform the following steps as an Administrator in the first sentence, you don’t need to mention it again.

Incorrect

To install the server, perform the following steps as an Administrator:

Open the Command Prompt as an Administrator.

Correct

To install the server, perform the following steps as an Administrator:

Open the Command Prompt.