Overview

The interactive Online Help module is pretty much just an electronic version of the old print-based User Guide document. is used to learn about the software (Instructional Mode) and to refresh one’s memory about the software (Reference Mode).

Instructional Mode
This provides contextual background to understand the software. It describes what tasks the software supports, describes how to use the software and provides examples to reinforce learning. It also gives procedural instructions for how to accomplish a task..

Reference Mode
This organizes the information for swift and efficient search access. The reference materials are often packaged as a Table of Contents or keyword-searchable Index..

A successful User Guide is based on an understanding of:

Target Audience	Who uses the software, their skill level, desires
Critical Tasks	What needs to be done, benchmarks
Environment	Necessary hardware and software, context

Fundamental Attributes
The User Guide document provides:

Clarity	The document is coherent and concise. You encourage speedy comprehension through use of graphics, diagrams, screenshots, tables, icons, step-by-step tutorials, etc.
Accuracy	The information reflects the interface and operation of the hardware and software (procedures have been tested and are replicable, interface screenshots are accurate, etc.)
Utility	The information provides useful procedural directions that address the Critical Tasks.
Relevance	The information content is appropriate to the Target Audience and is presented in a manner that is understandable to that group.
Comprehensiveness	The document includes all necessary information (as determined by user needs, Use Case Analysis, Critical Tasks, etc.)
Consistency	The format of the document is internally consistent and also conforms to other related documents (s.a. Technical Specifications and Functional Requirements) in terms of the ordering, classifying and presentation of information, terminology, etc.

Context Information for a User Guide

Introduction
Here are some of the things that you may want to present right up front in the document:

Environment
Identify necessary hardware and software.

Target Audience
Describe who they are; their skills & experience.

Purpose of software
Summarize the capabilities and intended use.

How to use this Document

Describe each section of document (contents, use, and interrelationship)

Presentational conventions (show examples of symbols, styles and syntax)

Reference/Support and Related documents

Feedback

How to report documentation or software problems

Information for Support and Contacts

 

Operational Flow
It's nice to have a conceptual map of how the software is organized. The customer experiences the software as a series of screen displays, so provide graphical examples that they can relate to.

Describe and illustrate all visible interface and design conventions within the software:

• Menu structure


• Toolbars


• Icons
and symbols

• Use and interrelationship of windows (s.a. popups)


• Keyboard conventions (shortcuts, dedicated keys)

 

Procedures
It is really important to focus on critical tasks, so this section comprises the bulk of the User Guide. Focus on Installation & Setup, Login, Shutdown, as well as the functional focus of the software. You should cover:

• Scope & Purpose of the Task (what it does & doesn't do)


• Materials necessary to complete the task (s.a. passwords, access authorization, data)


• Warnings and Conditions (what happens, consequences, results)

You may also want to address some of these issues:

• Input (data necessary to accomplish the task)


• Invocation (how to start a task, required/optional parameters, default options, order and syntax)


• Suspension (how to interrupt and restart a function during execution)


• Termination (what happens if the task is interrupted)


• Output (Results, changes to screen display, effect on files or data))

Support Info

• Terminology/Glossary


• Error States/Troubleshooting

• FAQ’s


• Error Messages


• Known problems


• Error Recovery