By: David McMurrey and Tamara Powell
Upon completion of this chapter, readers will be able to do the following:
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 be 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.
Filepad User GuideA user guide is a combination of many things presented in this online textbook. At its core its instruction writing; you need to be good at the writing style, headings, lists, notices, highlighting, tables, and graphics commonly used in instructions. 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:
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.
Here's review the common contents of user guides:
Instructions. The most obvious are those step-by-step directions on how to assemble, operate, or troubleshoot the product. Instructions in user guide should generally be task-oriented—that is, 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.
Reference information. User guides typically contain plenty of reference information, but only up to a certain point. For example, if there are numerous commands, a separate book for commands is necessary. Reference information in user guides is often presented in tables: columnal lists of settings, descriptions, variables, parameters, flags, and so on.
Getting started information. Some user guides will actually include brief tutorials that will help new users get acquainted with using the product.
About 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 will see considerable background in user guides for graphic or audio programs—you can't operate them without understanding the concepts of brightness, saturation, and hue; μ law, A law, and other such.
An important part of user guides—in fact, of almost any technical document—is the process that produces it:
Lorem ipsum
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 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.
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.