The more complex the product, the greater the page count in the accompanying user guide. If needed, you can create separate user guides for different aspects of the instructions, e.g., installation procedures, troubleshooting procedures, and commands for a new software product. A user guide can even contain a brief tutorial, getting users started using the product, but if there is too much tutorial, it too goes into a separate user guide.

Note that user guides need visuals, but may be relatively bland in terms of those visuals, since black and white illustrations are cheaper to print. This is especially important to note if the product updates frequently.

Content of User Guides

Many user guides contain the following content, as appropriate.

Instructions

The most obvious user guide contents are those step-by-step directions on how to assemble, operate, or troubleshoot a product. Instructions in a user guide should generally be task-oriented, written for specific tasks that users must perform. Instructions should generally use vertical numbered lists for actions that must be performed in a required sequence. Similar or closely related instructions in user guides should be grouped into chapters.

Precautionary Information

You’ll see notes, warning, caution, and even danger notices in user guides. These represent liability concerns for the manufacturer of the product.

Getting Started / About the Product

Some user guides include brief tutorials that will help new users get acquainted with using the product. User guides also provide some description of the product, a review of its essential features or its new features. Sometimes this information also gets put into a separate volume, if it is extensive. Typically, the volume will be called something like “Introducing New Product…”

Technical Background

Sometimes, user guides will include technical explanations of how the product works, what physical or chemical principles are essential to its operation, and so on. For example, you may see considerable background in user guides for graphic or audio programs, since you can’t operate them without understanding the concepts of brightness, saturation, and hue.

Reference Information

User guides typically contain reference information, but only up to a certain point. For example, if there are numerous commands for a new software product, you might have a separate user guide for commands. Reference information in user guides is often presented in tables, with columns of settings, descriptions, variables, parameters, flags, and so on.

Additional Components of User Guides

User guides have tables of contents, headings, lists of figures, and all of the characteristics of technical documents and reports. The following list additional components of user guides, since they are books. User guides may incorporate all or some of these components.

Front and Back Covers

On the front cover, you will typically see some or all of the following:

• Company name, company or product slogan and logo
• Product name
• Book title
• Trademark symbols
• Artwork

The back cover of hard copy user guides and manuals is usually very simple. Typically, it contains the book order number, the name of the company with appropriate trademark symbols, a copyright symbol and phrasing as to the ownership of the book, and a statement as to which country the book was printed in. You’ll also find bar codes on the back cover.

Title Page

The title page is typically a duplicate of the front cover, but with certain elements omitted. Typically omitted are the artwork, company or product logos, and slogans. Some technical publications omit the title page altogether because of the duplication.

Edition Notice

The edition notice occurs on the backside of the title page. If the technical publisher eliminates the title page, then the edition notice appears on the backside of the front cover.

Edition notices usually include the following:

• Date of publication – the year and sometimes the month that the book was published
• Edition number – whether the book is a first, second, or third edition.
• Product applicability – if the product is computer hardware or software, the edition notice typically indicates which platform, version, and release number of the product the book applies to
• Full title of the book – in italics
• Disclaimers – product manufacturers may state that they do not guarantee the book is technically correct, complete, or free from writing problems. that the product is free from minor flaws, or that it meets the needs of the customer
• Copyright symbol and statement – you’ll see the circle-C copyright symbol © and some statement about permissions, or a creative commons license
• Trademarks – some technical publications list known trademarks in the edition notice, including the company’s own trademarks and the trademarks of other companies referenced in the book. Or they may insert a statement that any references to trademarked product names are owned by their respective companies.
• Reader responses – sometimes, the edition notice will include some encouragement to customers to contact the company about product or documentation concerns. Instructions on how to contact the company are sometimes included in the edition notice.

Warranties

These are the “guarantees” that the company will support concerning its product. Sometimes these are published in the front matter of the book but, more appropriately from a book-design standpoint, they are printed on a separate card and inserted in the book or the product. As with edition notices, this is a company’s standardized text you simply insert into the book—do not change the text that you are given, which usually has been approved by company attorneys.

As a technical writer, be aware that companies sometimes maintain multiple versions of edition notices, safety notices, warranties, and communication statements. Make sure that you are using the right version.

Preface

The function of the preface is to get readers ready to read the book. It does so by:

• characterizing the content and purpose of the book
• identifying or even briefly describing the product the book supports
• explaining the type of reader for whom the book is meant
• outlining the main contents of the book
• explaining any special conventions or terminology used in the book

In traditional book publishing, the preface comes before the table of contents, but technical guides may place the table of contents earlier in the book for usability reasons.

Appendixes

Appendixes are for material that doesn’t fit in the main part of a book but is necessary in some way to readers’ understanding. Appendixes are often the place for big tables. An appendix is just like a chapter, except that it is named “Appendix A” and the headers and footers use are A-1, A-2, and so on for pages in Appendix A.

Glossary

Some technical publications include a section of specialized terms and their definitions. Notice that most glossaries use a two-column layout for the term and its definition. Definitions are typically not complete sentences. Multiple definitions are typically identified by Arabic numbers in parentheses. Glossary paragraphs also contain See also references to related terms.

Index

Indexes are also typically two-column and contain See also references to related terms.

Other Considerations for User Guides

You may encounter the following when creating a user guide:

Documentation Plan

User guides need documentation plans, which are internal supporting documents that specify content, audience, design, format, production team members, schedule, and other such information about a documentation project and its deliverables. The documentation plan represents an established plan agreed upon by everybody involved in the production process (both the user guide and the product it documents).

Prototype and Specifications

Important planning tools, which also serve as useful reference tools during a documentation project, include the prototype of the user guide and the specifications for the user guide. The prototype is a dummy version of the book with all planned components of the book (see the list on book-design components) and all planned elements (see the list under format and style). However, the prototype uses “Greeked” text (also known as Lorem ipsum). Typically, the prototype of the user guide is very brief: it needs to include only as many pages as it takes to illustrate every unique textual component and textual element that will be used in the user guide.

Specifications are descriptions of a book design in table form. Specifications describe every unique component or element of a book, so that it can be recreated by someone who might not have access to the electronic files, templates, or styles of that book.