This checklist helps you test User Guides and other technical documents.

Download: Technical Writing Templates

The first step is to ensure the following is in place.

1. Setup the necessary technical environment. Make sure this reflects the user’s settings or as close to as possible.
2. Print out the procedures. Follow the instructions as per the document. Aim to identify any gaps in the steps. Likewise, see if additional notes or warnings should be added.
3. Examine the screenshots. Does these provide real value? Do the screenshots reflect how the window or dialog box are populated? Is there data in the screenshots? If not, replace with something more meaningful.
4. Does the introduction orient the reader?
5. Does it highlight the necessary and mandatory prerequisites that must be performed?
6. Are the sections in a logical order? For example, is it arranged based on the user interface layout or on commonly performed tasks?
7. Is there an index? Are the entries used in a meaningful way?
8. If online, have meaningful keywords been added to the search engine?
9. Comprehensive – are all scenarios covered in the document? In other words, in addition to checking that the materials in the document are correct, you have to consider if other procedures are missing? To do this, you need to examine the application and see if, from a user’s point of view, if all tasks have been documented.

Download: Technical Writing Templates

User Guide Checklist

After this, examine the document using the following checklist.

Visual Cues

Have you provided visual cues to help the reader use the manual, understand concepts, and help them digest information faster?

You can achieve this by using some of the following:

1. Headings

2. Bullets

3. Bold

4. Arrows

5. Illustrations

Support Different Learners

Have you developed content that supports the following learning methods:

1. Visual

2. Audio

3. Touch

Examples

Provide the following types of examples to help the reader understand the materials:

1. Concrete examples, for example, how to perform a specific task.

2. Abstract concepts

Document Format

Have you delivered the user guide in a file format the suits the reader? For example, do they want the document in PDF or as Online Help or both?

Other factors to consider include:

1. Size – remember to optimize the PDF before publishing and to ensure it downloads fast.

2. Online/print – prepare the document in both online and PDF, if necessary.

3. Software/hardware environment – will the reader need any special software to view the documents?

4. Binding – if delivering a hardcopy, make sure the binding is reliable, so pages don’t fall out after a little use.

5. Protection – if the document will be used outdoors, make sure it is weather-proof.

Document Structure

Have you checked that the guide includes the following?

1. Headers, footers, navigation bars

2. Table of contents

3. Cross-references/links to related procedures/documents

4. Is each topic self-contained? In other words, can you perform the task from start to finish without having to go to another page?

5. Is there adequate white space?

6. Have you avoided large blocks of text?

7. Does the document separate conceptual, procedures, and reference materials?

8. Index

9. Glossary with product terminology and industry terms

Download: Technical Writing Templates

Introduction

In this section, you should introduce the User Guide and cover the following areas:

1. Intended readers – have you identified the different user types, for example, system operators, home users, and experts?

2. Have you identified the assumed level of experience and highlighted the sections of user guide which apply to them.

3. Software version – is the software release the User Guide refers to identified?

4. Purpose – have you described the purpose of the system and User Guide?

5. How to use User Guide document – have you described the intended use, section contents and relationship between sections?

6. Related documents – have you identified related documents?

7. Conventions – have you described symbols, conventions and syntax conventions used in the guide?

8. Problem reporting instructions – provided an email address so readers can contact you if they find an error or omission?

Overview

Have you outlined how the system works at a high level?

1. Identified key functions?

2. Inputs and Outputs – identified inputs what you, the reader, need to enter, and outputs, what you expect in response, for example, reports?

3. Provided further detailed explanation, if necessary.

4. Assumptions on user expertise, for example, experience or proficiency in related areas or previous training.

Procedures

This is usually the heart of the user guide. For each task, document the following:

1. Explain how to get started, for example, specific settings they need to make to use the application, such as installing a plugin or checking that a specific version of Java has been installed.

2. Describe the different functions of the system.

3. Provide cautions, warnings, and recommendations.

4. For each procedures, identify where in the application you perform this task, input operations and expected results. If necessary, include a screenshot that helps the reader understand the task. Avoid pointless eye candy screenshots.

5. Required parameters, optional parameters, default options and order/syntax

6. Provide examples

7. Identify known issue, likely errors, possible causes, and resolutions.

Reference

Have you identified and described all system capabilities, for example,

1. Describe the purpose of different buttons on the menu bars, what happens if they get greyed-out, how to change this, why this occurred, and how to reset window layout.

2. Describe the purpose of each field, identify mandatory settings, minimum or maximum settings, recommendations, and data input types.

Error Messages and Recovery Procedures

Have you identified and described all error messages and recovery procedures, for example,

1. Document all error messages.

2. Identify root cause.

3. Suggest recovery procedures

Glossary

Have you provided a list of ambiguous terms or terms users may not know to the reader.

Index

Have you provided an index? This is recommended for User Guides of 40 pages or more.

Document Control

Have you provided Document Control, Signoff and Change Record information?

Download: Technical Writing Templates