Practical models for technical communication - Shannon Kelley 2021

Creating Definitions and Descriptions
Technical definitions and descriptions

Effective technical communication includes the ability to define terms, describe methods, and clarify concepts. With specific and understandable definitions and descriptions, you can make a document more useable.

In Chapter 1, we introduced four guidelines to help your technical documents become more useable:

” Be clear

” Be precise

” Be concise

” Be accurate

Think of these concepts as four points on a compass. Taken together, they will orient your users and get them where you want them to go. As you create content, it’s wise to look up every so often and orient yourself, too.

Definitions and description often go hand in hand. Clear definitions require some description to be effective, though they may also rely on explanation and context. Context is the setting in which the word appears. For example, in a technical document, the word “screw” likely refers to a small, spiral-shaped metal piece used to attach two or more solid pieces together. In a text message from your angry friend (“screw you!”), the word is used in a different context and has a completely different meaning.

If the user has the potential to interpret words in too many ways, your document won’t succeed. In the worst-case scenario, a failed communication can have severe consequences.

Be Precise

A precise definition is one that requires exact and specific language, which can be more challenging than it seems. Beware of revolving door definitions such as this one: “Precision means to be precise.” Using a term or a variation of a term to define the term itself sends your user in a confusing circle. Your goal should be to explain the new term using words that the user is already familiar with. So what precisely does “precision” mean?

See Chapter 1 for more about precision.

Figure 8.1 defines “precision” using different definition strategies. In some cases, a term or concept may require an extended, multi-paragraph definition that includes deep research. For instance, we took a little more time to define “precision” here because it’s a word that many people think they already know. In technical fields, precision is essential and has a specific meaning that’s different from its common usage. We break the term down for you in this example to demonstrate its importance. Additionally, we use this term to show how you can begin making your definitions more precise.

For example, Alpacas of Doom! players use 3d6 to determine game effects. This language only feels precise to people who already know what 3d6 means. A more precise description would recognize that most board game enthusiasts know that 3d6 refers to a set of three six-sided dice, but newer players might need the additional description. This is why games that have been around for decades still include glossaries and descriptions—it’s no fun if you don’t know the rules of the game.

Figure 8.1. Definition Strategies. To define a term, break it down into its simplest parts. What is it made of? How is it used? What is it like? You can offer further explanation of a term by exploring what it is not or by using examples, and analogies.

Target Your Audience

How can you be sure you’re hitting the mark? In technical documents, your audience is the bull’s-eye, the center of your communication target. Always make sure your definitions answer the questions “What is it?” or “What does it involve?” in ways that make sense for your audience. As mentioned earlier, you might need to include analogies, examples, or comparisons to clarify your meaning.

One strategy for understanding your audience better is the creation of a user profile, a document that collects information about your audience from interviews, surveys, reports, or conversations with your client. The more you get to know about your audience, the easier it will be to decide what level of detail to use, what you need to define, and what can be left unsaid.

When your technical document has more than one audience segment, definitions can help you bridge the gap (figure 8.2). For example, in an audience assessment report for investors, Jason and Leticia identify that Alpacas of Doom! will most likely appeal to gaming enthusiasts who enjoy themed resource collection board games. They are the same crowd that is likely to already own games such as Settlers of Catan or Zombicide. To guarantee their document’s usefulness, Jason and Leticia need to take this audience’s experience into account and also recognize that some members of their audience may be entirely new to gaming.

Figure 8.2. Technical Knowledge in Audience Segments. Technical communicators often translate technical information from one audience segment to another.

Recognize Jargon

Industry-specific terminology, or jargon, requires definition when communicating with an audience outside your field. You also need to define words that have multiple potential meanings or acronyms. For example, take the word “heap.” To a computer scientist, it indicates a type of data structure, but to a layperson, it could mean a big pile. Be specific and determine what needs to be defined for clarity.

You should develop the habit of providing your own definitions instead of relying on dictionary definitions, which may not be specific enough for your communication needs. For example, if you’re writing a technical report on nanotechnology, you’ll find Oxford’s Dictionary of Mechanical Engineering more useful than Dictionary.com.

Jargon doesn’t just apply to complex technical terms. For instance, “hood” has a variety of specific meanings. Is it part of a ventilation system? Does it cover the engine of a car? Is it the part of a jacket or sweatshirt you wear on your head? In a professional kitchen, the hood is the ventilation and fire suppression system placed above cooking surfaces that draws smoke out and away from the kitchen and dining area. In a document discussing the legal and safety requirements for opening a restaurant, users need a specific definition to make sure they understand this industry-specific term.

When to Provide a Definition

The best time for a definition is immediately before or after the first use of the term. Whether or not you need to provide a definition depends on your audience. When you communicate with other experts in your field or employees in the same company, you can assume they share a common vocabulary and can leave out definitions to save time. If you have any reason to believe someone may not be familiar with a term, you should provide a definition. Three types of definitions we’ll cover in this chapter, in order of complexity, are parenthetical, sentence, and extended definitions.