Chapter 2: Applications of Technical Writing
2.14: Technical Definitions and Descriptions
By: Jonathan Arnett
Upon completion of this chapter, readers will be able to do the following:
- Explain and apply the 5 primary characteristics of technical definitions.
- Write a definition using appropriate content, descriptors, details, length, placement, and audience analysis.
- Avoid common technical definition problems.
- Explain and apply the 5 primary characteristics of technical descriptions.
- Write a description using the 6 common parts.
- Organize a description according to the 3 common organizational patterns.
When you think of the word "definition," what comes to mind? If you're like most people, you think of a dictionary's contents. What, then, does a dictionary definition contain?
Typically, dictionary definitions include a word's
- Standard spelling
- Syllable breaks
- Part of speech
- Current and archaic usage
- Variant spellings
- Variants including suffixes
If you've used a dictionary before, then none of these items should surprise you. Think, though... Are all dictionaries the same? And do they contain the same types of thing?
Not really. All dictionaries contain lists of words, but their contents are otherwise markedly different. A children's dictionary, for example, is much simpler and shorter than a "collegiate" dictionary, which is shorter and simpler than an unabridged dictionary, which pales in comparison to the Oxford English Dictionary, a two-volume monster that comes with a reinforced bookstand and its own magnifying glass.
All these different dictionaries share several characteristics, though, which are characteristics of any technical definition:
- their authors focus on a particular audience;
- their contents describe the object of attention;
- their contents clarify ambiguity;
- readers can use the contents to communicate across expertise levels; and
- readers can use the contents to solve problems.
At least one of these ideas should sound familiar. For example, focusing on a particular audience...haven't we mentioned that sometime before, in this very class?
As far as the other four elements go, the temptation is to say, "Well, yeah, of course. That's what a definition does." The trick, though, is to include the right information, structure it the right way, and build a good definition. That's what we'll talk about next.
As the name might suggest, a technical definition should explain what a thing is. But what does "explain what a thing is" actually mean? How long does the explanation have to be? And where does the explanation go?
The answers to these questions depend on the characteristics listed above and the noun (person, place, thing, idea, or process) you're defining, and we see the answers expressed in terms of content, length, and placement.
Let's talk descriptors that can be used in writing a definition. Here's a partial list of possible items you can use to define a noun:
- physical characteristics (a thing's color, shape, size, material, smell, taste, texture, and so on)
- operation (how it works, but not how to work it--that's what goes in instructions)
- analogies ("It tastes like chicken," for example)
- specific examples
More possible descriptors exist, but these are the usual suspects. You'll choose appropriate ones based on the situation at hand.
The kind of detail you'd include in a technical definition will vary. As with everything you write—and quite literally everything, whether you're writing it for this class, in future classes, or over the rest of your life—you need to consider your audience very carefully. For example, who is your audience? What is s/he like? What kind of language would you use? What medium would the audience respond to best? What kind of words will the audience respond to best? Et cetera... In short, analyze your audience carefully and tailor the content to that audience.
As an illustration of the kind of details you'd choose for a particular audience, let's think about defining the special steel used in the crumple zone of a car's frame. (If you don't know what a crumple zone is, it's an area of a car that's designed to get squished in a crash and absorb all the kinetic energy, thereby making the passengers safer.)
We're going to define the steel in this part of the car for three different audiences: you, a car manufacturer, and a car buyer.
For you, if I defined the steel as boron-doped high-austenite steel that undergoes a martensitic transformation in a crash, that would probably mean nothing because the information is too detailed. However, if I defined the steel in a modern car's crumple zone as relatively soft steel that suddenly stiffens up when it's put under stress, then you'd probably understand just fine.
For a modern car manufacturer, though, neither of those definitions would be detailed enough. The manufacturer would need to know specifics about how much boron went into the steel, how ductile (bendable) the steel is, how much stress the steel can take before it stiffens or breaks, and how quickly the steel stiffens when it's put under stress. For this audience, you'd need to write a highly detailed, highly technical definition.
A car buyer, on the other hand, simply doesn't care what kind of steel goes into a car's crumple zone. The only thing a car buyer wants to know is if the car's NTSA crash test ratings are good.
Another thing to consider is what sort of object/process/thing it is you're documenting. Some nouns just don't require certain types of descriptors.
As an illustration of necessary details for a particular subject, let's consider the same example again: the steel used in a car's crumple zone.
High-austenite steel is relatively ductile; its manufacturing process includes cold rolling, annealing, and quenching; and car manufacturers use high-austenite steel in crumple zones because this steel gets harder and stiffer under pressure, thus protecting drivers.
All of these properties make sense when we're talking about metal. In contrast, saying that a certain piece of high-austenite steel has a mottled gray appearance, makes a clang in the key of C-sharp, or tastes like chocolate chip cookies probably isn't relevant to anybody.
As we've already mentioned, the audience's need for information will drive how much information you provide. If the audience both needs and can handle a lot of information, then get super-detailed. On the other hand, if the audience only needs or only can handle the basics for whatever reason, then keep the definition short and include just the absolutely necessary information.
As an illustration of length, let's consider a dictionary definition.
A person who consults the Oxford English Dictionary probably wants detailed information about the many ways a particular word has been used over the centuries. Accordingly, the OED definition should be very long and full of examples.
In contrast, a middle-school student who just wants to know how to pronounce a word or find out a word's meaning won't want to read pages upon pages of etymology and usage. That student just wants the basic information and nothing more.
The audience's need for information and the type of information you're defining will also drive where you place definitions. Four major options include placing definitions in
- independent sentences
- dependent clauses
- parenthetical asides
- separate sections
If you're using relatively simple terms and have a knowledgeable audience, use simple, short definitions that fit within an ordinary sentence. If the definition is a bit more complex and/or your audience needs a bit more information, use a parenthetical statement. If you're defining complicated or detailed information, even to a knowledgeable audience, insert full paragraphs or subsections.
Sometimes, depending on the nature of the document that contains a definition, you'll refer readers to entire sections, such as footnotes, a glossary in the back of a textbook, or appendices at the end of formal proposals and reports (hint, hint on this last part).
In a separate sentence: Peanut butter is a paste made from ground peanuts.
In a dependent clause: Jim's Steakhouse uses wide-mouth Mason jars, like those used for preserving homemade jam, as water glasses.
In a parenthetical statement: Siamese cats—easily identifiable by their blue eyes, triangular-shaped heads, incessant yowling, and self-entitled attitudes—come from Southeast Asia.
When you write technical definitions, pay special attention to avoiding these three problems:
- audience-inappropriate content/language
- circular definitions
- synonymous definitions
We've already discussed this, so I'll keep my rap short: Analyze your audience and give your audience members what they need, in a way they can understand it.
Some bad definitions depend on the reader already knowing what the defined thing is/does.
Here's an example:
Super chlorination is a swimming pool chemistry technique that enables operators to achieve breakpoint chlorination.
Okay...but what is breakpoint chlorination?
Breakpoint chlorination is an elevated level of chlorine that swimming pool operators reach by super chlorinating the water.
Other bad definitions substitute one synonym for another. Here's an example:
Chloramines are another name for combined chlorine.
Okay...but what is combined chlorine? Oops. I've just defined a thing as itself.
Here's a revised version:
Chloramines are molecules of 'free chlorine' (the chemically active form of chlorine that sanitizes, oxidizes, and disinfects pool water) that met an organic substance, chemically bonded to the organic substance, became chemically neutral, and began to give off a foul odor.
This version is much better, yes?
Technical descriptions are similar to technical definitions. but technical descriptions can be stand-alone documents, whereas technical definitions are always components of a larger document. Furthermore, technical descriptions
- are usually longer than technical definitions,
- contain more detail,
- focus on functionality,
- often describe complicated subjects with multiple parts, and
- contain technical definitions.
Since technical descriptions are longer and more detailed than technical definitions, descriptions contain two major sections: Introductions and Body sections.
The contents of a technical description's introduction are very similar to the contents of a formal letter. In the first paragraph, you need to
- identify the thing to be described;
- provide some basic background information (purpose of writing, context of writing);
- give a brief overview of the thing to be described (what is it like, what is its purpose); and
- preview the rest of the document.
After the Introduction, a technical description's content will vary, depending on your audience and the thing being described. However, there are a few common themes in any technical description's body paragraphs.
The body paragraphs flesh out the background information in more detail. Again, like the body of a formal letter contains details about the letter's subject, the body of a technical description contains details about the background of the thing being documented. Of course, tailor the content based on your audience and the subject at hand.
The body paragraphs also include details about the various parts that make up the thing being described. If the thing is a physical object, you'll want to list and describe the various parts that make up the whole. If the thing is a place, then what makes it different from or similar to other places? If the thing is a process, then what are its necessary conditions and its various stages/steps?
A technical description's body can also include visual materials (and, conceivably, audio materials if the description is multimedia). These can be pictures, tables, diagrams, charts, graphs...if it's appropriate, put it in. One particular kind of visual material that we need to address under its own heading, though, is the specification.
The word "specifications" has two definitions. One of the definitions refers to a list (often a table) of technical details about the object or process you're documenting. These can be part of a technical definition and are often necessary in a technical description.
The second meaning, which we'll address here, refers to images that depict the subject of a description and include callouts (lines or arrows with text attached) to highlight that object's constituent parts.
Please note: Specifications are not descriptions. They may be part of descriptions, but specifications cannot stand alone.
Here's why: Imagine that you bought a new, top-of-the-line TV. You're quite excited, as it's a technologically advanced TV, with one bazillion features that you can program and customize for the world's most amazing TV experience.
You unpack the box and, instead of an owner's manual, all you find is a single piece of paper that pictures the TV's remote control, with labeled arrows to each button. One button is labeled "Skip."
- What will the TV do if you press the button?
- What will be skipped?
- Can you undo a skip?
- What if you press the button twice? Three times?
- Can "Skip" be used while watching regular TV, or just during DVR replay?
- Does "Skip" have meaning for programming your DVR?
All these questions need answering before you dare press the "Skip" button. You'd be very unhappy if you missed recording this week's episode of Game of Thrones or somehow recorded over the Jersey Shore marathon...
Long technical definitions need their own organization strategies, just as any piece of writing does, but technical descriptions usually rely on one of three organization schemes:
Your choice of an organization strategy will depend on the kind of thing you're describing. In general, you'll always want to go from general to specific, for you need to begin by defining the thing and then proceed by breaking it down thematically. What that theme is, though, depends on the nature of the thing being described.
For example, let's say you're documenting a bicycle. Would it do any good to just start naming pieces?
Okay...here's the front wheel, and here's the seat, and here's the handlebars...ooh! My favorite part, the chain guard!
Of course not; you need some sort of internal logic to the parts list. A logical scheme might be to begin with major systems—frame, wheels, gears, brakes—and then describe how the systems work together or go into more detail about the parts that compose each of these systems.
What about describing the construction of a four-barrel carburetor? You'd likely want to describe how the parts fit together, so a spatial organization scheme would make sense, complete with an exploded-view diagram of the parts. (As a completely irrelevant side note, in the year 2000, I met the inventor of the four-barrel carburetor; he was in his early nineties, and he was volunteering as a math tutor at a community college in Arizona. He was a very nice fellow.)
But what about describing a process, like smelting iron? Giving a tour of the factory wouldn't make much sense, would it?
Here's the blast furnace, and over here is the rock crusher. And then on this side, we've got the mold-making shop and a pile of spare wheelbarrow tires.
No... you’d want to proceed chronologically, step-by-step, through the process.
First, dump trucks haul in raw ore and pour it into this bin. Then we use a bucket loader to transfer the ore into this machine, where we pulverize it. Then we load the crushed ore into these crucibles and roast the ore until the iron melts out. From that point, we...
You get the idea.