Practical models for technical communication - Shannon Kelley 2021
Descriptions
Technical definitions and descriptions
Think of descriptions as an extreme version of the extended definition. They go beyond the initial questions of “What is it?” and “What does it entail?” to include other questions, such as:
” What are its parts?
” What does it do?
” How does it work?
Descriptions are used in a variety of documents to describe an object or process. In the workplace, you find them included in purchase orders and as parts of a longer technical document, such as manuals, reports, and instructions. A description focuses on specific details like background, features, physical attributes, function, qualities, and visuals.
Like definitions, descriptions use specific, accurate, and concise language to help the user better grasp the concepts in the document. Also, building a bank of descriptive phrases helps you and your collaborators provide accurate, consistent information.
When to Use
Descriptions are best used when you need to define a process or make the user aware of the parts they need. Often, visual aids like photos and diagrams accompany descriptions to help the user recognize and interact with the described item or process. Even without images to help, description is the tool we use to help someone else “see” the thing we’re describing when they haven’t encountered the item or concept before.
To understand the complexity of writing an effective technical description, imagine what it’s like to explain 5G networks to someone who has never used a smartphone. To define this new concept, you may need to define other terms along the way. For example, you would need to explain that a 5G network is a form of broadband mobile communication that is wireless and allows the transfer of data from one mobile device to another at a rate faster than 4G. From there, you would need to define broadband, wireless, and 4G. Definitions require you to imagine what it is like to hear about something for the first time.
Here’s another example from Alpacas of Doom! The game uses standard six-sided dice with images on four sides and two blank sides. This definition helps the user make a distinction between regular dice with pips (dots) and the regular dice used for this game. In the instructions, the next description would tell you how to use them and for what purpose.
How to Use
When crafting descriptions, use concrete language. Concrete language includes words that are sensory and tangible. Concrete language tends to be mostly nouns (things you can see and touch) and verbs (things you can do).
Use adjectives and adverbs sparingly in technical descriptions. Too many adjectives, especially in a continuous string, can cause confusion in surprising ways. It might seem like you’re being specific when you use multiple adjectives, as in “5G broadband wireless mobile communication network.” But this mouthful description will only make sense to people who already know what you’re talking about.
One type of description you are likely to encounter is the product description. To develop a product description that details an object’s physical characteristics, ask questions that focus on elements that you can see or touch. The object you are describing may require spatial and visual descriptions, temporal (time-based) and action descriptions, or any number of similar combinations. For example, if your job is to describe the features of a device, your description will require focus on size, shape, or color.
Examples of questions you might ask when writing a product description start simple and become more granular as you dive deeper into the product. For example, you might start with the question, “What is the first thing I notice about this product?” Chances are that what you notice first will also catch other people’s attention first, which gives you a place to start when organizing your thoughts and drafting your description.
Other questions to ask yourself when writing a product description include the following:
” What are its distinguishing characteristics?
” What are the primary uses of this product?
” How is this product activated?
” Are there any clear dangers associated with using this product?
” What are the primary and secondary colors of this product?
In Alpacas of Doom!, Jason and Leticia want to use a simple dice system to add an element of chance. They asked themselves questions to figure out how they’d describe the dice to investors and manufacturers. This description is necessary for product development and will also help them understand game mechanics. They want to get the description right because it’s not cheap to create and manufacture specialized dice (figure 8.7).
Another type of description you are likely to encounter is the process description. Process descriptions explain how complex events occur with attention to sequence, timing, movement, and necessary tools. Here are some questions to ask when developing a process description:
” What equipment is needed?
” Do users need to set up a space?
” What is the chronological order of each step in the process?
” What are the outcomes of each step?
Figure 8.7. Targeted Description. Jason and Leticia aim for precision in their description of the dice. The product description is for a specific audience: investors and manufacturers.
Since we just received Jason and Leticia’s description of the dice their game uses, let’s see a process in which these unusual dice are used (figure 8.8). Leticia and Jason answer questions to develop equipment for Alpacas of Doom! and consider further questions to determine how the equipment is used. These descriptions are important to players’ understanding of game-play as well as the overall theme of the game.
Figure 8.8. General Description. The goal of this process description is to make sure players can easily understand how to use the game’s specialized dice. Simple, descriptive language helps players get to the fun part faster.
