Practical models for technical communication - Shannon Kelley 2021
Why definitions and descriptions matter
Technical definitions and descriptions
Abstract: Technical definitions and descriptions give meaning to a process or procedure and can be found in a variety of technical documents. Technical communicators generally use three types of definitions: parenthetical, sentence, and extended definitions. A description is a kind of long-form definition that requires precision. In order to create a useable definition or description, you must know who is going to use it, when they’re likely to use it, what they need to know, and what they already know. Audience plays a big role in determining the amount of information you need to create effective definitions and descriptions.
Looking Ahead
1. Why Definitions and Descriptions Matter
2. Creating Definitions and Descriptions
3. Parenthetical Definitions
4. Sentence Definitions
5. Extended Definitions
6. Descriptions
7. The Known-New Contract
8. Legal and Ethical Implications
Key Terms
” Chain Method
” characteristic
” class
” concrete language
” context
” definition
” description
” extended definition
” Fork Method
” glossary
” jargon
” Known-New Contract
” name
” negation
” parenthetical definition
” process description
” product description
” sentence definition
” user profile
Why definitions and descriptions matter
When you were in grade school and didn’t know the meaning of a word, your teacher most likely told you to look it up. Now, as a technical communicator, it’s your job to know the terminology of your specific field, to use it accurately, and to be able to explain it precisely to someone else. You can’t tell your audience to grab a dictionary. You are the dictionary.
The good news is that you don’t have to know everything. But you do need to know how to use your expertise to define unfamiliar terms and situations. A definition is a short explanation of the meaning of a word or phrase. Technical definitions help users understand an unfamiliar term or clarify a word that has multiple meanings. A description is an extended explanation that focuses on physical characteristics of an object or situation. For an object, a description might include its size, weight, shape, color, material, and use. For a situation, the description might include its purpose, frequency, duration, location, and other factors.
Though the specific words you need to create a definition or description will depend on your audience and your industry, the way you create these technical elements will follow a standard format, which we’ll cover in this chapter.
As an expert (or expert-in-training), you need to determine how and when to provide definitions and descriptions to your audience. Never assume that a user knows everything you know. Keep in mind that your background and education have given you a specialized vocabulary. When you understand a subject thoroughly, it can be difficult to imagine what someone new to the subject knows or doesn’t know. To combat this tendency, keep these questions in mind:
” What does my audience need to know?
” How much detail does my audience need?
” How will my audience use this information?
In your own projects, your job is to determine if the user needs a quick reminder of a term’s meaning or an extensive description of an object’s parts, purpose, and function. To illustrate this, we’ll revisit Leticia and Jason’s board game project, Alpacas of Doom!, from earlier in the book. Their game uses a variety of familiar concepts (dice, alpacas) with adjustments for gaming purposes. To communicate these new ideas to their boss and potential funders, they need to define how and when these modified elements are used. Documents that alter familiar items and introduce new concepts present an ideal opportunity for exploring definitions.