ITS 311: IT Communications

Chapter 11: Preparing Manuals and Product Support Items

Objectives:

This chapter combines concepts from previous chapters to create a more complex product: a manual. Objectives important to this chapter:

  1. Writing strategies
  2. Manual preparation
  3. Other product support items
Concepts:

The text explains that creating manuals for users or technicians requires several of the techniques described in previous chapters. A manual is likely to contain definitions, descriptions, instructions, and process analyses.

Manuals often include other components listed in the text, such as Frequently Asked Questions (FAQ), glossaries, indexes, tables of contents, and statements of warranty.

Writing strategies

A technical writer needs to know something about the intended audience for a manual. A user manual is typically written with less technical detail than a service or maintenance manual. Knowing what kind of manual is being prepared, and for whom it is being prepared provide most of the information needed to choose the right focus for the document.

Manual preparation

The research for a manual may be like other research for other projects. In general, the newer the product the greater the need to consult the product developer. For example, if the project is to prepare a setup manual for a popular model of a well-known printer, the necessary information may be found in existing documentation on the manufacturer's web site. Researching such material, especially for established products, can be quick and easy. If the project concerns a recently developed product, for which there is little or no existing documentation, it becomes necessary to consult someone familiar with the new product. Often, there will be no one familiar with such a product other than the staff who developed it.

The text refers us to the previous chapters about definitions, descriptions, instructions, and process analyses. These are standard components of a manual: a device must be described, terms must be defined, instructions must be given for use and/or service, and the use of the device is typically discussed as a process analysis. The standard considerations about page design, graphics, white space, etc. apply to each portion of the manual.

Other possible components should be considered and used as needed. For example, the longer a manual is, the greater the value of an index and a table of contents. A maintenance manual might cover only the maintenance issues that a specific technician is expected to resolve, but a more general manual should include operating instructions, so that the technician knows what to expect the user to do with a device, and may better diagnose issues not covered in the manual.

Other product support items

The text discusses preparation of quick reference material for technical equipment. A user may expect to find a quick start guide as part of a manual or as an accompanying document. This may take the form of a list of the most commonly used functions, a quick reference chart of commands, or a picture of the device with notes about what each button does, such as the image on the right.

Such material may be most useful to a user who has a general idea about what a device is for, but needs specific knowledge to use it. For example, the device shown on the right is meant to act as a cell phone. Users typically understand how to make a call, but need to know that they should

  • click the trackwheel to answer a call
  • press and hold the escape button to end a call

This information should be covered in the user manual, but may be addressed on a small quick reference card that the user may find easier to absorb.