Planning a User Guide - Part 2/5 - Determining the Overall Scope

Photo by NordWood Themes on Unsplash

In the previous post, I described how to do an audience analysis for a user guide. Understanding the audience will help you make design decisions that will serve your users in a better way. Once you have understood what the audience needs, the next step -- and the topic of this post -- is to plan the overall scope of the manual.

I have outlined below, a list of sections that most manuals consist of. It's a comprehensive list and it's quite possible that your manual won't need all these sections. This post will also help you decide which sections you need.

Cover Page

The Cover Page contains the following details:

• The title of the user guide.
• A company logo.
• The version number of the product. 

Optionally, the Cover Page can also mention the publish date and a one-line copyright notice. Sometimes, these details are mentioned on the page immediately following the cover page.

Legal Notices

The Legal Notices section may extend over several pages. This section begins with your company contact details which typically contain the following:

• Corporate address.
• Phone number.
• Website URL.
• Email

The actual Legal Notices appear after the contact details. Here's a list of notices that are most commonly used.

• Copyright notice.
• Terms of use including any disclaimers.
• A mention of industry standards and warnings, if applicable.
• A note about trademarks.

Preface

The Preface is usually a single chapter and contains the following details:

• What this guide contains: A brief description of what this user guide contains.
• Intended audience: A brief description of the intended audience and assumptions about the domain and technical knowledge they need to use the manual effectively.
• Providing feedback about the user guide: An email address where users can provide feedback about the user guide.
• Typographical Conventions.: Describes the various fonts used in the document and what they signify.

Table of Contents

In digital documents, it is a good practice to have a Table of Contents with page numbers and links to various chapters.

You can decide how deep you want to nest the table of contents. I suggest including the main sections of each chapter. Going one level below the chapters adds value but going deeper than that might just add clutter.

Introduction

The Introduction is the first real-content chapter in the user manual. It is usually a single chapter but if the contents are large enough then it could be broken down into multiple chapters. A typical Introduction contains the following details:

• A high-level explanation of the business domain, the value proposition of the software, important concepts, and terminology.
• High-level architecture/design diagram with a brief description of its components.
• What's new in this version.

System Requirements

Many user guides include System Requirements in the Introduction but I prefer it to be a separate chapter by itself. This chapter lists the minimum hardware and software requirements to run the software.

Installation and Setup

This section is usually split into multiple chapters. They contain the following details:

• Installing the software, along with any special setup instructions.
• Uninstalling the software.

Administration

The Administration section is usually split into multiple chapters. It describes all the features that contribute towards administering and maintaining the product. This includes features such as creating and managing users; managing security and permissions; managing quotas; networking; various rules; etc.

Using the Software

This section contains a description of the features available to regular users of the software. It describes everything a user can do with the software. This section is usually split into multiple chapters.

Most user guides follow a sequence of the menu items and other UI elements. A high-level grouping of the topics can be done based either on user stories or on high-level menu items.

A good user guide may also provide background information about the concepts that a user should understand to use the software well.

Troubleshooting 

All software has known issues and known pitfalls. The Troubleshooting section describes various issues a user might face while using the software and how to overcome them. This section may be split into multiple chapters for troubleshooting the installation and troubleshooting usage issues.

Getting Help

This chapter describes what a user should do if the troubleshooting instructions do not solve their problem. You would typically include the following information in this section:

• A brief mention of all the log files, where to find them, and what they contain.
• Details of online support forums that your company hosts or supports.
• Information about how to reach customer support and the details that should be included in the support request for speedy resolution. These details are usually screenshots of the problem along with appropriate log files.

Quickstart Guide

For a complex software, the Quickstart Guide contains the most basic information that a user needs to know to get started with the product. A Quickstart Guide follows the philosophy that underlies the design of many software products: make basic features easy to use and complex features possible to use. The quickstart guide contains a description of the basic features. You can also think of this section as the 'Start Using Software X Within an Hour' guide. 

Unless it's really short, the Quickstart Guide should be bundled as a separate document.

Working Examples

This section is useful if your software supports an API or has an in-built scripting interface. It contains working examples of how to use the API and/or the scripting language. It's usually a good idea to bundle this section as a separate document.

Appendix

The Appendix contains additional information that is useful to the user. It may also contain information that cannot be cleanly mentioned anywhere else in the manual. Here are some examples of what you might want to include in your Appendix:

• Glossary of important terms.
• Keyboard shortcuts.
• Error codes. 
• Function reference.