10: Descriptions
- Explain a technical description.
- Exemplify sample definitions and descriptions.
An important part of technical and report writing is the use of definitions, descriptions, and instructions. They often work together to clarify the purpose and information in a technical document for an audience. This series of three chapters look at these three elements: definitions, descriptions, and instructions, more closely, so that you understand how to incorporate them into your technical documents to achieve clarity and conciseness. For that reason, you will find this introduction at the beginning of each chapter to remind you of their interconnectedness.
Definitions
We grow up reading these from the time we are in elementary school. They are one of the more common patterns of organization used. Definitions can be simple short insertions in a sentence to clarify a term, or they can be an entire document known as an extended definition.
Descriptions
These are similar to a definition but can be longer, more detailed, and have a visual representation to further explain a concept. More than likely, you have read these as well. Descriptions explain objects, mechanisms, and processes – and they do so in a way that whatever is being described is easily understood. If a description of the greenhouse effect was created for specialists in the field, it might be more complex. If this same idea was written for a general audience, the language would be simplified.
Instructions
Instructions provide step-by-step explanations of how to do things: assemble something, operate something, repair something, or explain a personal process (enrolling in college, for example) so that readers may better understand it and possibly use it themselves.
What are Technical Descriptions?
Descriptions and definitions are closely connected. Often, a technical writer will include description in an extended definition or include definition while writing a description. We all use the word description loosely to refer to practically any discussion or explanation. But in a technical writing context, description means the detailed discussion of the physical aspects of a thing. That means discussing things like color, shape, size, weight, height, width, thickness, texture, density, contents, materials of construction, and so on.
The following sentence is not a description; it explains the function or purpose but provides little or no physical detail. It is a definition.
A computer diskette is a device used for storing electronic data.
However, this sentence is definitely description:
The common computer diskette is 3.5 inches by 3.5 inches and approximately 1/8 inch thick.
Contexts for Description
Descriptions are a common element in technical writing. Certain types of technical writing feature description:
- Accident reports requiring plenty of description.
- Product specifications—documents that describe the design and features of a new or changed product—have plenty of description.
- Instructions often require description to help readers visualize what they are doing and what they are working with.
Contents and Organization of Descriptions
Below is a review of the sections you will commonly find in descriptions:
Introduction. Plan the introduction to your description carefully. Make sure it does all of the following things (but not necessarily in this order) that apply to your particular description:
- Indicate the specific object about to be described.
- Indicate what the audience needs in terms of knowledge and background to understand the description.
- Provide a general description of the object.
- Include an overview of the contents of the description.
Background. If what you are describing is not likely to be familiar to most of your readers, add some background before you plunge into the description. If you are about to describe an SGO/3 density gauge to non-specialists, you should first discuss what it is, what it does, and where it is used.
Visual. The easiest way for someone to understand something is to see it. Visuals help with this. In addition, the parts of the object or process are often labeled (See Chapter ___ on Document Design) so the reader can better understand how each part works in conjunction with the entire item.
Discussion of the parts or characteristics. The main part of your description is the discussion of each part or characteristic. You must divide the item you are describing into parts, or characteristics, or both.
Parts are easy: for example, a wooden pencil has lead, a wooden barrel, an eraser, and a metal clip. Characteristics are describable aspects of a thing but are not parts: for example, the pencil has a certain weight, length, width, and so on.
If you were a budding real-estate tycoon and had to describe a vacant lot for company files, you'd probably describe it by its characteristics: its location, square footage, terrain, vegetation, access to utilities, and so on. (Check out the description of the Primitive Stone Scraper - part of it is arranged by characteristics and part by parts!) If the parts section follows a visual, it is often organized to match the visual. For example, it might list the parts in clockwise order or from top to bottom of how they are labeled on the visual. In addition, the descriptors labeled on the visual match what is listed in this section exactly. Consistency is key.
Once you've divided the item you are describing into parts, characteristics, or both, your next job is to describe each one. For mechanical items, it works well to start by defining the part, by explaining its function. After that, you describe the part from general to specific, using any of the sources of description that are appropriate.
Discussion of the related operation or process. At some point in a description, often at the end, it is useful to summarize the operation or process associated with the object you're describing. For example, if you've just described a mechanical pencil, you could briefly explain how it is used. If you've just described a snowflake, you could discuss the process by which it formed.
Note: In description, you can mix other types of writing. You'll find yourself explaining functions, defining terms, and discussing a bit of process as you describe. That's not a problem as long as the primary focus and the majority of the content is truly description.
Sources of Description
When you write a description, you need to think about the kinds of descriptive detail you can provide. Sometimes, descriptions are rather weak in this area. Use the following list to plan your description or to review a description you have written. Think of the categories of descriptive detail you could provide, or use the following list to identify categories you have not used:
|
color height width shape weight |
materials texture width location methods of attachment |
depth amount pattern, design ingredients age |
subparts length finish temperature moisture content smell |
Note : This is a typical or common model for the contents and organization—many others are possible.
Anatomy of a descriptive paragraph. Typically, it starts with some statement about the purpose or function of the part, with the descriptive detail following. Descriptive detail draws upon the "sources" of description—such things as color, shape, width, and height.
Graphics and Format in Descriptions
Visuals : In most descriptions, you'll need at least one illustration of the thing you are describing, with a caption , labels pointing to the parts, and callouts to highlight important information. See the chapter on Document Design Basics for more on captions , labels, and callouts
Headings. In descriptions, you'll want to use headings and subheadings to mark off the discussion of the individual parts or characteristics. Remember that, ideally, you want to describe each part in a separate paragraph or section—and flag that discussion with a heading. If you have a background section, use a heading for it too. See the chapter on Document Design Basics for the specific requirements of headings.
Lists. Lists are not nearly so important in descriptions as they are in instructions. However, if you itemize parts or subparts or list specifications, these are good situations for lists. See the Chapter on Document Design Basics for the specific requirements of lists .
Special notices. In descriptions, there is no role for special notices as there is in instructions. In a description, readers will not be following a procedure and therefore, will not be running any risks of damaging equipment, wasting supplies, or injuring themselves or others. However, you may find the N ote special notice to be useful to emphasize important points or exceptions . See the Chapter on Document Design Basics for a complete discussion of the proper use of these special notices as well as their format and placement within instructions.
GENERAL DESCRIPTION TIPS
- Descriptions are more detailed than definitions and typically include a visual representation.
- Technical descriptions discuss things like color, shape, size, weight, height, width, thickness, texture, density, contents, materials of construction, and so on.
- Descriptions should include an introduction, background, visual elements, and discussion of the parts and process.
- Description format should be accessible and include elements such as callouts, captions, labels, headings, lists, and special notices.
This work "Descriptions" is a derivative of Definitions, Descriptions, & Instructions CC-BY Amber Kinonen , Technical Definitions CC-BY Amber Kinonen , Technical Description: What Does it Look Like? CC-BY David McMurrey , and Technical Writing for Technicians CC-BY Will Fleming, used under a CC BY 4.0 license. "Descriptions" is licensed under CC BY 4.0 by Mary P. Richards.