How to Write a User Guide

©  Ugur Akinci

An excellent and affordable entry-level Online Course: Technical Writing 101

A user guide consists of the following components:

• Front Cover
• Front Matter
• Table of Contents
• List of Figures
• List of Tables
• Introduction
• Chapter 1
• Chapter 2

…

• Chapter N
• Appendix 1
• Appendix 2

…

• Appendix N
• Glossary
• Index
• Back Cover

Not all of these components are always present in every user guide. Some user manuals for example will not have a Glossary or a List of Figures. It just depends the kind of guide you are writing and its size and complexity.

FRONT COVER should be simple enough not to confuse the reader but still detailed enough to communicate the most important basic information about the product or software. A front cover should not have a page number.

At a minimum, a goof Front Cover should have the NAME of the product or software in question; VERSION number; DATE of the document; COMPANY LOGO and COMPANY INFORMATION.

Click here for a more detailed explanation of how to design a great front cover for a technical document.

FRONT MATTER, just like the Front Cover, also does not have a page number and it’s the page coming right after the Front Cover. It includes copyright information, company web site, and any legal disclaimers, warnings or disclosures that might be appropriate. If the document has an ISBN number or any other publication identification information that belongs to the Front Matter as well.

TABLE OF CONTENTS should list all chapters and sub-chapters with page numbers, not more than 3-levels deep. Human attention wavers at anything deeper than 3 levels. (This is true for the INDEX as well.) Most text editors like Microsoft Word or Adobe FrameMaker have their built-in TOC generators that pick up paragraph styles and convert them into a TOC. Every technical guide should have a TOC unless it’s a 3 or 4 page short document. Anything over 20 pages and/or 10 chapters/sections definitely deserves a TOC.

LIST of FIGURES and TABLES. If you have just a few figures and tables and a short manual you would not need to have a list. However, if you have lots of figures and tables (say over 15 or 20) you should definitely have a list and list all figures and tables with their CAPTIONS (or TITLES) and PAGE NUMBERS. That way your readers can find the figures and tables they want easily.

INTRODUCTION is important since this is where you explain WHAT the document is all about and for which AUDIENCE it is written. Here you can also give a thumbnail sketch of what’s ahead, including a short one-sentence summary of chapters (best presented in a table format). An explanation of special terms, icons, abbreviations, acronyms and other special information that the user should know about to make sense of the manual… they all belong here. CONTACT INFORMATION (Company Name, Address, telephones, web and email information) can be included here as well although some writers prefer to include that in the FRONT MATTER and BACK COVER.

CHAPTERS should cover distinct groups of information devoted to one topic. You’d be the best judge of which information goes into what chapter. Chapters should closely follow the Documentation Plan, which in turn should be prepared in beginning of a technical writing project and approved by the management or the client.

Click here for a more detailed explanation of how to write a chapter for a technical document.

APPENDIX is for the kind of information that the read should be aware of but either does not fit in smoothly with the flow of the main chapters in the manual or consists of reference information. For example, the WIRE GAUGE information in an electronics manual, or all the HEXADECIMAL COLOR CODES in a manual about web design would make a useful appendix.

GLOSSARY is a life-saver for a lot of readers if the manual if full of technical terms that are not widely known. It’s good practice to assume that your readers might not be familiar with your terms, acronyms and abbreviations and list them in a tabular form and in alphabetical order in a Glossary.

INDEX is a very important part of any technical document, especially if you are writing something that is hundreds of pages long (which is not unusual in technical communications). Creating an index (or “indexing” as it’s sometimes also referred to) is such a specialized function that there are technical communicators professionally known as Indexers who do nothing but indexing on a full-time basis. They even have their own associations. There are a few useful rules of indexing that you should apply every time you generate an index. Click here to learn more about this crucial task that needs to be performed correctly.

BACK COVER should be elementary and contain only absolutely necessary information. That includes the name, address and logo of the company; the title, version, and document number of the manual; any copyright information, etc. Keep the back cover as simple as you can.