Chapter 4: Writing Definitions, Descriptions, and Instructions

Technical Definitions ^[27]

A technical definition helps a reader understand items such as an object or process. It can be short and embedded in a document, or it can be its own document. The purpose of a definition is to provide clarity to the reader. The extent of the definition depends on your audience’s background knowledge in regards to what you are writing about. For example, it could be a parenthetical definition that follows a potentially unknown term, a full sentence used after a term to further define it, or it may be an extended definition, or larger definition. In fact, a writer may use many methods within the definition to help the reader better understand it.  Some methods that can be used include graphics, examples, comparisons, and contrasts.

Technical Descriptions^[28]

The biggest hurdle you may face in writing a description is remembering what the term means as it is used in this context. We all use the word description loosely to refer to practically any discussion or explanation. But in this context, it 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.

For example, this sentence is not really description in our sense of the word: A computer diskette is a device used for storing electronic data.

It explains the function or purpose but provides little or no physical detail. It is a definition. However, this sentence is very definitely description: The common computer diskette is 3.5 inches by 3.5 inches and approximately 1/8 inch thick.

Be sure to check out the example descriptions available with this chapter.

Contexts for Description

As mentioned earlier, descriptions are common element in technical writing—just not quite in the same way that instructions are. Descriptions appear more often as a sentence or two here, a paragraph there, or a whole section elsewhere. Certain kinds of technical writing feature description:

• Accident reports requiring plenty of description.
• Product specifications—documents that describe design and feature of a new or changed product—have plenty of description.
• Instructions often require description to enable readers to visualize what they are doing and what they are working with.

Contents and Organization of Descriptions

The following is a review of the sections you’ll commonly find in descriptions. As you read, check out the example 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 the thing you are describing is not likely to be familiar to most of your readers, consider adding some background before you plunge into the actual description. If you are about to describe an SGO/3 density gauge to non-specialists, you’d better first discuss what in the world the thing is, what it does and on what part of the planet it is used.

Visual. The easiest way for an individual to understand something is to see it.  Visuals help with this. In addition, the parts of the object or process are often labeled so that the reader can further 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 thing 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 in the examples; part of it is arranged by characteristics and part by parts!)  If this 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 thing you are describing into parts, characteristics, or both, your next job is to describe each one. For mechanical things, 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.

Notice that in description, you can mix other kinds of writing. You’ll find yourself explaining functions, defining terms, 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.

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.

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:

Figure 12. Schematic view of descriptions. Remember that this is just a typical or common model for the contents and organization—many others are possible.

Miscellaneous Concerns

In descriptions, you’ll probably find yourself puzzling over how to handle numbers, abbreviations, and symbols:

Numbers. Remember that technical writing breaks some of those rules you worked so hard to learn in past writing classes. In the technical writing context, we are often vitally concerned about numbers and want them to stand out. This means that you should use numerals in running text when the number indicates an exact, measured, or measurable amount or when it represents a critical value. For example, in these sentences, it seems to matter that the numbers are exact:

The cup is 3 inches in diameter.
Use 4 tacks to fasten the poster to the wall.

However, this does not mean using numerals for indifferent values. For example, in this sentence, there is nothing heart-stopping about how many sections the report has:

The report contains four major sections.

See the section on numbers vs. words for further details.

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.

Abbreviations. In technical writing, we expect to see abbreviations. Use them in your description freely. Remember the rule on punctuating abbreviations—punctuate them only if they spell a word (for example, “in.”). Remember too that abbreviations do not go up against the number they are used with (for example, make that “8 mm tape” or “8-mm tape” but not “8mm tape”).

Symbols. The most common problem with symbols in instructions and descriptions has to do with inches and feet. If you’re writing instructions for a carpenter’s dream project where there are feet and inches all over the place, use the symbols ” (inches) and ‘ (feet). However, if you cite inch and foot measurements only a few times, use the word or abbreviation instead.

Graphics and Format in Descriptions

In most descriptions, you’ll need at least one illustration of the thing you are describing, with labels pointing to the parts. See the section on graphics for more on creating graphics, formatting them, and incorporating them into your descriptions.

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 section on headings for the specific requirements.

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 section on lists for the specific requirements.

Special notices. In descriptions, there is nothing like the important role for special notices as there is in instructions. After all, if it really is a description, readers should not be trying to follow any procedure, and therefore should not be running any risks of damaging equipment, wasting supplies, screwing up the procedure, or injuring themselves or others. However, you may find the note special notice to be useful to emphasize important points or exceptions. See the section on special notices for complete discussion of the proper use of these special notices as well as their format and placement within instructions.

Instructions

Go to the following website and read it in its entirety for information on writing instructions:

Creating Rhetorically Effective Instruction Manuals ^[29]

Common Components of Instructions ^[30]

Title

Keep it simple but clearly identify the task that will be performed.  Use a “how to” or gerund (ing verb) when crafting it.  Make sure the title adequately reflects the product and process users will be working on. It should be simple and clear.

Introduction

The goal of the introduction is to give general information about the process. What is it? Why should it be done? It is an overview of the process and why it is important. Often times, the writer lists the benefits of completing the process so that the reader feels good about the task he or she is about to complete.

Tools & Materials

List the items necessary to complete the task so that the reader can gather and organize them before starting the process.  Consider using a bulleted list or some other formatting tool so that it is easy for the reader to skim through.

Visuals

Your reader will need visuals to refer to and act as a guide through the process. Remember to label the visuals as Figure 1, Figure 2, and so on, and then title each visual so the reader knows what he/she is looking at. Often times, the visual is referred to within the step-by-step part of the instructions.

Step-By-Step Instructions

Use a numbered list of step-by-step instructions for completing the process. Consider transitional words to keep the reader on track. Examples of transitions include: first, next, then, and finally. Also, write in clear and complete sentences throughout this section. In addition, refer to the visuals in this section. For example, a writer might include a phrase such as: “See Figure 3.” This will help the reader see the relationship between the steps and the visual.

Another reminder is to avoid the word “you” as you write; use the imperative mood. For example, instead of writing “You then push the blue button” write “Next, push the blue button.”

One last reminder is to explain to the reader why to do or not do something that may have negative consequences. This will help the reader have a positive experience completing the process.

Troubleshooting

A troubleshooting section helps the reader solve common problems.  It is when someone tells the user to do something and adds, “If that doesn’t work, try this…” Sometimes, telling the reader what not to do is just as important as stating what to do. If you have several troubleshooting tips, organize this section so the reader can easily find the particular difficulty he or she needs solving at the moment. Therefore, make this section reader friendly and skimmable.

Conclusion

End the instructions with positive comments about the product and/or the process the user just completed.  Sometimes there is a phone number for a Help Line if further assistance is needed. The benefits can also be restated but in different words but make sure not to use the exact words from the introduction. Readers don’t like to read the same exact words/phrases/sentences in the conclusion as they did in the introduction because it feels like the writer was too lazy to actually work on the document.

Warnings

Just because this is listed last in this section it doesn’t mean it is any less important than the other parts of the document or that it actually goes last in the document.  In fact, the writer has to decide where in the document to put the warnings. They should be dispersed throughout. Also, remember legal and ethical obligations. It is the writer’s job to protect the reader from harm or damage. This being said, any set of instructions needs a careful balance of warnings strategically placed throughout the document. If the writer overuses them, there is a risk of scaring the user or making it so that the reader doesn’t want to carry out the process being described in the instructions. If the writer under-uses warnings, there is a risk of someone getting injured.

In addition, don’t create instructions where the user has already completed the process and injured him/herself before the warning comes. If someone is injured as the results of hidden or omitted warnings, it is the responsibility of the technical writer whose job it is to keep the reader safe.

In fact, there are standard precautionary statements that are color-coded and used for danger, warnings, cautions, and notes or notices. Click on the following link and carefully review them: Precautionary Statements. Do NOT skip looking over this link! You will be expected to incorporate information from in it into the instructions you will create for the course.