4.5.1. Instructions format

This is a review of the most common instructions format. It is not unique, but will vary according to the specifics of the situation (J.Hartley 1978).

Introduction:

- indicate the specific tasks or procedure to be explained as well as the scope of coverage (what will not be covered);

- indicate what the audience needs in terms of knowledge and back­ground to understand the instructions;

- give a general idea of the procedure and what it accomplishes;

- indicate the conditions when these instructions should (or should not) be used;

- give an overview of the contents of the instructions.

All of these elements may not be necessary, and some of them can combine neatly into single sentences.

General warning, caution, danger notices. Instructions must often alert readers to the possibility of ruining their equipment, disrupting the pro­cedure, and hurting themselves. Also, instructions must often emphasise key points or exceptions. For these situations, use special notices - note, warn­ing, caution, and danger notices.

Technical background or theory. At the beginning of certain kinds of instructions (after the introduction, of course), you may need a discussion of background related to the procedure. For certain instructions this back­ground is critical, otherwise, the steps in the procedure make no sense.

Equipment and supplies. Most instructions include a list of the things that need to be gathered before you start the procedure. This includes equipment, the tools you use in the procedure and the supplies, the things that are consumed in the procedure. In instructions, these typically are listed either in a simple vertical list or in a two-column list. Use the two-column list if you need to add some specifications to some or all of the items, for example, brand names, sizes, amounts, types, model numbers, and so on.

Graphics in instructions. Graphics are crucial to instructions. Some­times, words simply cannot explain the step. Illustrations are often critical to readers' ability to visualise what they are supposed to do, therefore this is a common, most helpful and most wanted part of instructions.

4.6. User guides

A user guide is essentially a document containing instructions on in­stalling, using, or troubleshooting a product. A user guide can be very brief or it can be a full-length book. In cases of a more complex product some ele­ments of user guides should be divided into separate volumes, especially the installation procedures, troubleshooting procedures, and the commands.

Information Included in User Guides

The common contents of user guides are the following:

• Instructions: The most obvious are those step-by-step directions on how to assemble, operate, or troubleshoot the product. Instructions in a 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: notes, warning, caution, and even danger notices represent liability concerns for the manufacturer of the prod­uct.

• About the product: description of the product, a review of its essen­tial features or its new ones.

• Technical background: sometimes user guides include technical expla­nations 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 con­cepts of brightness, saturation, and other such.