Knowledge Test

Take this short quiz to find out what you already know about Technical Descriptions and Definitions.

Descriptive technical writing uses a combination of visuals and text to both “show” and “tell” the reader about the information being conveyed. Like more creative descriptions, technical descriptions sometimes draw on the “five senses” and metaphorical comparisons (analogies) to allow the reader to fully conceptualize what is being described. More often, however, they rely on concrete, measurable descriptors. Technical descriptions can take many forms, depending on purpose and audience. Descriptions can range from a brief sentence, to a paragraph, a whole section of a report, or an entire manual.  Poorly written technical descriptions can cause confusion, waste time, and even result in catastrophe!  Technical product descriptions are often legally required to ensure safety and compliance. Attention to detail is critical.

Product specifications require detailed descriptions of design features; instructions often require specific descriptive detail to “show” the reader what to do. Some general categories of technical descriptions include the following:

• Mechanism Descriptions: Provide a detailed overview of the physical aspects of a tool, machine or other mechanical device that has moving parts and is designed to perform a specific function. These could be product descriptions for sales or manufacturing, documentation of design specifications, infographics, etc.  This chapter focuses in detail on this kind of description.
• Process Descriptions:  Detail a series of events (natural/biological/ecological, mechanical, social, or psychological phenomenon) that happen in a particular sequence in order to achieve a specific outcome. These can be categorized into non-instructional processes (such as a process that analyses how an internal combustion engine works, or natural processes like photosynthesis) and instructional processes (such as recommended/required procedures and explicit step-by-step instructions to be followed). (See Chapter 9.3 for detailed information on Writing Instructions).
• Definitions:  Clarify the specific meaning, often related to a specific context, or express the essential nature of the terms being defined. These can range in length from a simple clarifying phrase to a glossary, to an extended document of several pages. Definitions will often include detailed descriptions and visuals to illustrate ideas. Extended definitions are created using various rhetorical strategies: classification, exemplification, analogy and comparison, history, and components, along with relevant visuals. You can find a good example of such a description on the NASA Mars Perseverance Rover site; the overview of the spacecraft that conveyed the Perseverance Rover to Mars includes various rhetorical strategies. Can you pick them out? Click on the link below to view a student PowerPoint presentation on how to write effective definitions for technical purposes. This presentation is included with the express permission of the student.

(Technical Definitions, 2015)

Definitions in Technical Writing – Student Presentation

Technical Description of a Mechanism

Mechanism descriptions should provide a clear understanding of the object being described, including

• General appearance and physical properties
• Overall function/purpose
• Component parts
• How the parts interact to create a functioning whole.

The reader should be able to clearly picture, and therefore understand, the nature of the object being described, what it does, and how it works.

In order to achieve this clarity for the reader, the writer must choose significant details and organize information logically. Select details that can be described precisely and measurably, such as

Depending on the reader’s need, the description may range from a general overview requiring only a few sentences to a multi-chapter manual detailing every aspect of the mechanism’s parts and functions in order to troubleshoot technical problems and complete repairs. For a fun example of the latter, see the Star Trek: The Next Generation: Technical Manual (cover depicted in Figure 9.5.1), which provides detailed descriptions of all equipment and technology used aboard the fictional U.S.S. Enterprise-D.

Before you begin to draft your description, you must consider your purpose and audience: Why does your audience need this description? What will they use it for? For example, are you describing different types of solar panels for the average consumer to help them choose the one that best fits their needs? Are you giving schematics to technicians and installers?

Once you have your purpose and audience clearly in focus, draft a description that includes the following elements:

1. Definition: What is it, and what is its main purpose?
2. Overview: Describe the mechanism’s overall appearance (“big picture”).
3. Components: Describe the main component parts in labeled sections; consider the order of information carefully here. Create a logical connection between each component described.
4. Explanation: How do the parts work together to fulfill their function? What key principles govern its functioning? Consider how much detail is necessary here for your intended audience.
5. Visuals: Include graphics that clearly illustrate the mechanism and/or its parts. Show the device as a whole; consider showing specific details in expanded views, cut-aways, or labeled diagrams. You may even embed or link to videos showing the device in action.
6. Conclusion: Depending on the purpose, you might review the product’s availability, manufacturing, costs, warnings, etc.)
7. References: Include sources you have used in your description, or additional sources of information available (if relevant), including specifications, codes, regulations, and manufacturer’s datasheets.

You might consider using a template, like the Technical Description Template below, keeping in mind that while templates can be helpful guides, they do not provide much flexibility and may not work for all situations.

Notations

Physical characteristics, such as temperature, dimensions, weight, and distance are customarily noted with numerical information that must be written with consistency and accuracy. Learning about technical notations will help you answer questions like: “When do I spell out a number and when do I use a numeral?” “Do I place a space between a number and the value?” “Do I add an ‘s’ for multiples of any value; for example, do I add an ‘s’ to ‘cm’ for centimeters over one?” For a primer on technical notations, see the IEEE article: Using Numbers in Technical Documents (Elliott, 2016). Also check out the APA Style section: Numbers (2019).

Sample Descriptions

Examine the description of the “Up Goer Five” in Figure 9.5.2 (click on image for larger version). Who might the intended audience be?

Figure 9.5.2 A description of the blueprints for NASA’s Saturn Five rocket using only the 1000 most commonly-used English words (Munroe, n.d.).

Compare the description in Figure 9.5.2 to the information given on the NASA website about the Mars Curiosity Rover.

Note the differences in the level of detail, vocabulary, and overall purpose of the descriptions.  If you used the information on the NASA site to fill in the Technical Description Template, you might end up with something like the following chart. Objectives

You may find that some of these elements are not necessary; again, consider what your target audience already knows. Strike a balance between unnecessarily stating the obvious and incorrectly assuming your readers have knowledge that they lack.

In refining the details of your description and its component parts, consider the following:

• Organization: Use a logical principle to organize your description
  

  

  • Top to bottom (or foundation upward)
  • Left to right (or right to left)
  • Inside to outside (or outside to inside)
  • Most important to least important features
  • Central component to peripherals
  • Material properties, etc.

• Language:  Use specific, precise, concrete terms – avoid vague or overly general terms
  • Use correct terminology and notations – define terms as necessary for your audience
  • Use analogy to describe an unfamiliar thing in terms of a familiar thing
  • Use objective language – no “ad speak” or subjective terms
  • Use present tense, active verbs to describe how the device appears and what it does
  • Use words that create vivid and specific pictures in the reader’s mind.

EXERCISE 9.5.1 Practice technical description

Choose a common, everyday object (such as one of the objects in Figure 9.5.4) and draft a technical description for an audience unfamiliar with the object. Start by imagining a target audience and purpose, and then try filling in the Technical Description Template with detailed information. Using the information in your template, draft a short description of 1-2 paragraphs, and add properly-captioned visuals.

Figure 9.5.4 Common objects for practice description. Sources: Corkscrew and bicycle images: https://www.flickr.com/photos/dogbomb/527733767 and https://www.flickr.com/photos/8205548@N08/4607907389. CC BY 2.0.

How to Develop Your Descriptions (McMurrey, 1997-2022)

The ability to explain complex, technical matters with ease, grace, and simplicity so that nonspecialist readers understand almost effortlessly is one of the most important skills you can develop as a technical writer. This ability to “translate” difficult-to-read technical discussions is important because so much of technical writing is aimed at nonspecialist audiences. These audiences include important people such as supervisors, executives, investors, financial officers, government officials, and, of course, customers.

Here are some strategies for “translating” technical discussions, that is, specific strategies you can use to make difficult technical discussions easier for nonspecialist readers to understand.

You use your understanding of your audience to decide

• What information to include in the document
• What information to exclude from the document
• How to discuss the information you do include in the document

Translating is particularly important because it means supplying the right kinds of information to make up for the reader’s lack of knowledge or capability. Translating thus enables readers to understand and use your document. Some combination of the techniques discussed in this chapter should help you create a readable, understandable translation:

This list by no means exhausts the possibilities. Other techniques include:

• Headings. See the section on using headings that break up text and emphasize points and on how to construct headings that guide readers from section to section.
• Lists. See the section on constructing lists that break up text and emphasize points and on how to construct headings that guide readers from section to section.

Definitions of unfamiliar terms

Defining potentially unfamiliar terms in a report is one of the most important ways to make up for readers’ lack of knowledge in the report subject.

Comparisons to familiar things

Comparing technical concepts to ordinary and familiar things in our daily lives makes them easier to understand. For example, things in the world of electronics and computer—a downright intimidating area for many people—can be compared to channels of water, the five senses of the human body, gates and pathways, or other common things. Notice how comparison (highlighted) is used in these passages:

Elaborating the process

Explaining in detail the processes involved in the report subject can also help readers. Consider a paragraph like this one, containing only a sketchy reference to the process:

This brief reference can be converted into a more complete explanation as is illustrated here:

Providing descriptive detail

Descriptions also help nonspecialist readers by making the report discussion more concrete and down-to-earth:

Providing illustrations

Illustrations—typically, simple diagrams—can help readers understand technical descriptions and explanations of processes. You can see the use of illustration in the FAS example above: epicanthic folds and the philtrum are labels in the diagram.

Providing examples and applications

Equally useful in translating complex or abstract technical discussions are examples or explanations of how a thing can be used. For example, if you are trying to explain a LINUX command, showing how it is used in an example program helps readers greatly. If you are explaining a new design for a solar heating and cooling system, showing its application in a specific home can help also.

Now here is a passage with a longer, extended example:

Shorter sentences and paragraphs

As simple a technique as it may seem, reducing the length of sentences can make a technical discussion easier to understand. Consider the following pairs of example passages, the second versions of which contain shorter sentences. (The passage still needs other translating techniques, particularly definitions, but the shorter sentences do make it more readable.) Notice too that shorter paragraphs can help in the translation process, not only in the example below but throughout this chapter.

Original version: longer sentences

Revised version: shorter sentences

Stronger transitions and overviews

Transitions and overviews guide readers through text. In difficult technical material, transitions and overviews are important. (For in-depth discussion, see transitions.)

• Repetition of key words. As unlikely as it may seem, using the same words for the same ideas is a critical technique for comprehension in technical discussions. In other words, don’t refer to the hard drive as a “fixed-disk drive” one place and as “DASD” (an old IBM term meaning direct access stationary drive) in another. Same goes for verbs: stick with either “boot up” or “system reset,” and don’t vary.
• Arrangement of key words. Equally important is how you introduce keywords in sentences. If your focus stays on the topic in each sentence of a paragrah, place the keyword at or near the beginning of the second and following sentences. However, if the topic focus shifts from one sentence to the next, use the old-to-new pattern: start the following sentence with the old topic and end the sentence with the new topic. For more detail, see the discussion of topic strings.
• Transition words and phrases. Examples of transition words and phrases are “for example,” “however,” and so on. When the discussion is particularly difficult and when repetition and arrangement of keywords is not enough, use transition words and phrases. See transitions.
• Reviews of topics covered and topics to be covered. At certain critical moments within and between paragraph (or groups of paragraphs) occurs a transitional device that either captures what has been discussed in a short phrase, previews what is to be discussed in the following paragraphs, or both. The latter device is also called a topic sentence.

The “in-other-words” technique

Another way of translating technically difficult content is to give the reader two “looks” at the same idea by restating the difficult-to-understand version in simpler terms. The second, simpler explanation is often preceded by a phrase such as “in other words” (IOW). Here are two examples of this IOW technique:

Posing rhetorical questions

In technical writing, you occasionally see questions posed to the readers. Such questions are not there for readers to answer; they are meant to stimulate readers’ curiosity, renew their interest, introduce a new section of the discussion, or allow for a pause:

Explaining the importance

Some translating techniques work because they motivate readers. Sometimes readers need to be talked into concentrating on difficult technical discussion: one way is to explain to them or to remind them of the importance of what is being discussed. In this example, the last paragraph emphasizes the importance):

Providing historical background

Discussion of the historical background of a technical subject helps readers because it gives them less technical, more general, and sometimes more familiar information. It gives them a base of understanding from which to launch into the more difficult sections of the discussion:

Reviewing theoretical background

To understand some phenomena, technologies, or their applications, readers must first understand the principle or theory behind them. Theoretical discussions need not be over the heads of nonspecialist readers. Discussion of theory is often little more than explanation of the root causes and effects at work in a phenomenon or mechanism. In this example, the writer establishes the theory and then can go on to discuss the findings that have come about through the use of NMR on living tissue.

Combining the translating techniques

This last section concludes the techniques for translating difficult technical prose to be presented here. However, take a look at writing in fields you know about, and look for other kinds of translating techniques used there. Now, here are several extended passages of technical writing that combine several of these strategies.

References

American Psychological Association. (2019, September). Numbers. APA Style. https://apastyle.apa.org/style-grammar-guidelines/numbers

Brightwell, S. (2015). Writing Definitions. Slideshare. https://www.slideshare.net/safwanb/technical-defintions

Brightwell, S. (2015). Writing technical descriptions. Slideshare. https://www.slideshare.net/safwanb/writing-techn     ical-descriptions-50178324

[Corkscrew and bicycle images]. https://www.flickr.com/photos/dogbomb/527733767 and https://www.flickr.com/photos/8205548@N08/4607907389. CC BY 2.0.

Elliott, C. M. (2016, March 16). Using numbers in technical documents. IEEE PRO COM. https://procomm.ieee.org/using-numbers-in-technical-documents-2/

Israel, R. (2020). Getting creative with organizing principles for blogs. Say it for you. https://www.sayitforyou.net/checklist-for-business-blog-writers/getting-creative-with-organizing-principles-for-blogs/

McMurrey, D. (1997-2022). Translating technical discussions. In Online technical writing. https://mcmassociates.io/textbook/translating.html

Morton, Isaac. (n.d.). Definitions in technical writing. PPT.

Munroe, R. (n.d.). “Up Goer Five”.  https://xkcd.com/1133/ Also see “1133 Up Goer Five – explained.” Explain xkcd wiki. https://www.explainxkcd.com/wiki/index.php/1133:_Up_Goer_Five . CC-BY-NC 2.5.

NASA. (n.d.). Spacecraft. Mars Curiosity Rover. https://mars.nasa.gov/msl/spacecraft/rover/summary/

NASA. (2020). Spacecraft. Mars 2020 Mission Perseverance Rover. https://mars.nasa.gov/mars2020/spacecraft/overview/

Sturnback, R. & Okuna, M. (1991). Star Trek: The Next Generation: Technical manual. New York: Pocket Books.