Online Technical Writing — User Guides

A user guide is essentially a book-length document containing instructions on installing, using, or troubleshooting a hardware or software product. A user guide can be very brief—for example, only 10 or 20 pages or it can a full-length book of 200 pages or more. While this definition assumes computers, a user guide can provide operating instructions on practically anything—lawnmowers, microwave ovens, dishwashers, and so on.

The more complex the product, the greater the page count. when this happens, some elements of the user guide get split out into their own separate volumes—especially the installation procedures, troubleshooting procedures, and the commands. A user guide can even contain a brief tutorial—for example, getting users started using the product—but if there is too much tutorial, it too goes into a separate book.

Style and Format for User Guides

A user guide is a combination of many things presented in this online textbook. At its core is instruction writing; you need to be good at the writing style, headings, lists, notices, highlighting, tables, graphics commonly used in instructions. (For an overview of these elements, see the page-design chapter in this online textbook.) As a set of instructions, a user guide should use the style and format that is presented elsewhere in this online textbook:

Instructions—and therefore user guides—also make abundant use of:

Components of User Guides

As a book, a user guide must have some combination of the standard book-design components such as the following:

There is no standard combination or sequence of these elements; every company does it differently. Details on the contents, format, and design of these elements can be found in the book-design chapter.

Information Included in User Guides

Here's review the common contents of user guides:

Examples of User Guides

Consider a few examples:

Delarina WinFax LITE User's Guide. This book is 5.5 × 8.5 inches and under 150 pages. It is uses by-chapter pagination, with new chapters and sections beginning on a righthand page.

Process and Internal Documents for User Guides

An important part of user guides—in fact, of almost any technical document—is the process that produces it:
  1. Initial planning—Early planning on a user guide involves needs assessment (is any documentation needed at all?), audience analysis (who will be using the user guide; what are theiur needs?), task analysis (what will users use the product for; what are their common tasks?), library plan (what books, in addition to a user guide, are needed to support the product?), and so on.

  2. Documentation proposal—If you are working freelance or as part of an independent documentation firm, you may have to write a proposal in an effort to win a contract to do a certain technical documentation project.

  3. 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 resembles the documentation proposal in certain ways, but the plan represents an established plan agreed upon by everybody involved in the production process (and that means both the user guide and the product it documents).

  4. 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 like the following, instead of real text:

    Lorem ipsum dolor sit amet, consectetuer adipiscing elit, sed diam nonummy nibh euismod tincidunt ut laoreet dolore magna aliquam erat volutpat. Ut wisi enim ad minim veniam, quis nostrud exerci tation ullam corper suscipit lobortis nisl ut aliquip ex ea commodo consequat. Duis autem vel eum iriure dolor in hendrerit in vulputate velit esse molestie consequat, vel illum dolore eu feugiat nulla facilisis at vero eros et accumsan.

    Typically, the prototype of the user guide is very brief: it need 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.

  5. Template and style catalog—A well-designed user guide, and a well-designed process to produce that user guide, should include templates and style catalogs. A template is an electronic file that defines such aspects of the user guide as page size, headers and footers, page-numbering style, regular and special page layout, and other such detail.

    A style catalog is also an electronic thing that defines the format and style of textual elements such as headings, headers, footers, lists, paragraphs, tables, and so on. For example, a style for a "heading 1" might specify 24-point Arial bold with 24 picas above and 12 picas below. Styles help you create a user guide more efficiently; styles also help you maintain consistency in the format and style of that user guide.

  6. Multiple review drafts & sign-off—A good process for the production of a user guide also includes several drafts that editors, technical experts, usability testers, and documentation team members can review and provide comments on. You as writer then implement those comments and produce a new draft for these same people to review again. When everybody is satisfied with the draft of the user guide (or worn out or out of time), they sign off on the user guide, and it can then go into "production," which means producing the finished bound copies.

As you can see, a user guide brings together many of the topics covered in this online textbook. If you are taking a technical writing course, you probably cannot implement all these features and phases of a user guide. Get with your instructor to see which are required.

Return to the table of contents for the Online Technical Writing Course Guide (the online textbook for online technical communication courses at Austin Community College and other institutions worldwide).
This information is provided and maintained by David A. McMurrey. For information on use, customization, or copies, e-mail