THIS CHAPTER DISCUSSES definitions, descriptions, and instructions. The first step is to define these three terms:
A definition is typically a brief explanation, using words and sometimes graphics, of what an item is or what a concept means. You could write a definition of file format or of regenerative braking.
A description is typically a longer explanation—usually accompanied by graphics—of the physical or operational features of an object, mechanism, or process. You could write a description of a wind turbine, of global warming, or of shale-oil extraction.
A set of instructions is a kind of process description, almost always accompanied by graphics, intended to enable a person to carry out a task. You could write a set of instructions for installing a new roof or for using an app on your tablet.
Although each can appear independently, definitions, descriptions, and instructions are often presented together in a set of product information. For instance, a store that sells building materials for homeowners might create a product-information set about how to lay a brick patio. In this set might be definitions of tools (such as a mason’s line), descriptions of objects (such as different types of edging materials, including plastic, metal, masonry, and wood), and step-by-step instructions for planning, laying, and maintaining the patio.
Regardless of your field, you will write definitions, descriptions, and instructions frequently. Whether you are communicating with other technical professionals, with managers, or with the public, you must be able to define key concepts, describe processes, and explain how to carry out tasks.
FOCUS ON PROCESS: Writing Definitions, Descriptions, and Instructions | |
In writing definitions, descriptions, and instructions, pay special attention to these steps in the writing process. For a complete process for writing technical documents, see “A Process for Writing Technical Documents” in Ch. 1. |
|
PLANNING | For definitions, you will need to decide where to place the definition. Parenthetical and sentence definitions can be placed in the text, in a marginal gloss, in a separate hyperlinked file, in a footnote, or in a glossary (an alphabetized list of definitions). An extended definition can be a section in the body of the larger document or can be placed in an appendix. |
DRAFTING | For descriptions, you will need to indicate clearly the nature and scope of the description, introduce the description clearly, provide additional detail, and conclude the description. For instructions, you will need to design the instructions based on how your readers will be using them, and you should include appropriate graphics. Do everything you can to ensure readers’ safety. |
REVISING | If you can, carry out usability testing on any instructions you write. |