Skip to main content

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.

Labels:

Comments

Post a Comment

Popular posts from this blog

Commenting your code

Comments are an integral part of any program, even though they do not contribute to the logic. Appropriate comments add to the maintainability of a software. I have heard developers complain about not remembering the logic of some code they wrote a few months back. Can you imagine how difficult it can be to understand programs written by others, when we sometimes find it hard to understand our own code. It is a nightmare to maintain programs that are not appropriately commented. Java classes should contain comments at various levels. There are two types of comments; implementation comments and documentation comments. Implementation comments usually explain design desicisions, or a particularly intricate peice of code. If you find the need to make a lot of implementation comments, then it may signal overly complex code. Documentation comments usually describe the API of a program, they are meant for developers who are going to use your classes. All classes, methods and variables ...
Post a Comment
Read more

Inheritance vs. composition depending on how much is same and how much differs

I am reading the excellent Django book right now. In the 4th chapter on Django templates , there is an example of includes and inheritance in Django templates. Without going into details about Django templates, the include is very similar to composition where we can include the text of another template for evaluation. Inheritance in Django templates works in a way similar to object inheritance. Django templates can specify certain blocks which can be redefined in subtemplates. The subtemplates use the rest of the parent template as is. Now we have all learned that inheritance is used when we have a is-a relationship between classes, and composition is used when we have a contains-a relationship. This is absolutely right, but while reading about Django templates, I just realized another pattern in these relationships. This is really simple and perhaps many of you may have already have had this insight... We use inheritance when we want to allow reuse of the bulk of one object in other ...
3 comments
Read more

Planning a User Guide - Part 3/5 - Co-ordinate the Team

Photo by  Helloquence  on  Unsplash This is the third post in a series of five posts on how to plan a user guide. In the first post , I wrote about how to conduct an audience analysis and the second post discussed how to define the overall scope of the manual. Once the overall scope of the user guide is defined, the next step is to coordinate the team that will work on creating the manual. A typical team will consist of the following roles. Many of these roles will be fulfilled by freelancers since they are one-off or intermittent work engagements. At the end of the article, I have provided a list of websites where you can find good freelancers. Creative Artist You'll need to work with a creative artist to design the cover page and any other images for the user guide. Most small to mid-sized companies don't have a dedicated creative artist on their rolls. But that's not a problem. There are several freelancing websites where you can work with great creative ...
Post a Comment
Read more