User Guide Checklist

This checklist summarizes the recommended structure and contents for User Guide documents.

Introduction

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

– Intended readers – identify the different user types, for example, system operators, home users, and experts. For each, identify the assumed level of experience and highlight the sections of user guide which apply to them.

– Software version – identify the software release the User Guide refers to.

– Purpose – describe the purpose of both the system and User Guide.

– How to use User Guide document – describe the intended use, section contents and relationship between sections.

– Related documents – identify any related documents.

– Conventions – describe symbols, conventions and syntax conventions used in the guide.

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

Overview

Outline how the system works at a high level.

– Identify the key functions

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

– Provide further detailed explanation, if necessary.

– 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:

– 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.

– Describe the different functions of the system.

– Provide cautions, warnings, and recommendations.

– 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.

– Required parameters, optional parameters, default options and order/syntax

– Provide examples

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

Reference

Identify and describe all system capabilities, for example,

– 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.

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

Error Messages and Recovery Procedures

– Document all error messages.

– Identify root cause.

– Suggest recovery procedures

Glossary

Provide list of ambiguous terms or terms users may not know to the reader.

Index

This is recommended for any User Guides of 40 pages or more.

Document Control

Ensure there is Document Control, Sign-off and Change Record information.

Document Structure

Ensure that the guide has the following:

– Headers, footers, navigation bars

– Table of contents

– Index

– Glossary with product terminology and industry terms

– Cross-references/links to related procedures/documents

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

– Is there adequate white space?

– Have you avoided large blocks of text?

– Does the document separate conceptual, procedures, and reference materials?

Visual Information

In addition to text information, provide 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:

– Headings

– Bullets

– Bold

– Arrows

– Illustrations

Different Learning Styles

Where possible, develop content that supports the following methods of learning:

– Visual

– Audio

– Touch

In addition, provide the following types of examples:

– Concrete examples

– Abstract concepts

Document Format

Produce 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:

– Size – remember to optimize the PDF before publishing.

– Online/print – prepare the document in both formats if necessary.

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

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

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