How to Write a Useful User Guide

The objectives of producing a User Guide are:

  • Help users get comfortable with the system
  • Meet contractual obligations as a part of project execution
  • Reduce software support requirements

The starting point to writing the User Guide is to identify the target audience.  Prior to commencing work on the User Guide, it is important to familiarize oneself with the system that has been developed. The User Guide can then be structured into the various sections described below.

Introduction: This opening section should describe the purpose of the document and explain how the User Guide is organized. This will help the users to go to the relevant sections when they seek help. The system requirements for running the application should also be included here.

Intended Audience: This section should clearly spell out who the target audience is.

Functional overview of the system: This should provide an overview of the system from a business perspective. The approved Functional Specifications Document would be an excellent source for this information.

Mapping System roles and tasks: The tasks that each user may perform are defined in the system. Various user roles may include system administrator, data entry operator, supervisor and manager. The mapping of user roles to various tasks would be detailed in the approved Functional Specifications Document and can also be validated through interviews with the users of the system. This information should be represented in a tabular form. Similar tasks performed by various user roles should be grouped together to avoid repetition.

Explaining how to use the system: A good way to describe the system is through screenshots. Users should be provided guidance on how to navigate to a particular screen to perform a task. The User Guide should clearly explain when a function should be used and what actions should be avoided. If there are any pre-conditions for performing certain tasks, they should be detailed here. This section would contain step by step instructions to perform various tasks mapped to a particular role. The expected output should also be provided here in the form of screenshots.

Appendix: All documents that have been referenced in producing the User Guide should be listed here.

The responsibility of developing the User Guide is usually with the Business Analyst. The language used should be appealing to the business users and be devoid of technical jargon. Care should be taken to acknowledge the licensing agreements and trademarks where applicable. It is also highly recommended to publish the contact information of the author and the organization that produced the User Guide. Preparing User Guides should not be treated as a mere documentation activity. Once the initial draft is written, it would be ideal to have it reviewed by the developers in the project team to ensure that the understanding is correct and descriptions of the functionalities are accurate.

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.