Practical models for technical communication - Shannon Kelley 2021
Legal and ethical implications
Technical definitions and descriptions
Clear and accurate definitions help users navigate challenging technical issues. As a result, definitions carry legal and ethical implications for you as a technical communicator and for your employer.
See Chapter 2 for more on ethical responsibility in technical communication.
The user of your document doesn’t have access to your thought process. They can’t see what you think, and they don’t necessarily know what you know. Definitions help reduce the chance that users might misinterpret language in a document and make mistakes based on this misinterpretation. It’s kind of like showing your work in your math homework.
Although there is such a thing as user error, it’s a good idea as a technical communicator to assume that misunderstandings or confusion are not the user’s fault. This assumption will help you stay sharp while drafting important documents that carry real consequences.
Conveying an accurate interpretation of facts is not only an ethical issue but also one of safety. If procedures and important terms are vague or incomplete and you work in a potentially dangerous environment, the consequences could be injury or death. That may seem scary right now, but it’s a reminder to get a handle on writing clearly and accurately so that you are prepared if you ever need to take on a project with this level of responsibility.
Case Study
Alien Meets Alpaca
This case study is an opportunity for you to put into practice what you’ve learned. In any kind of writing, including technical communication, knowing your audience allows your message to be more effective. Look at the following case study to consider what needs to be defined and how much, what parts require a description, and how best can you explain all of this to the user:
During the early days of development for Alpacas of Doom!, Leticia and Jason challenged each other to describe elements of their game to a visitor from outer space. For example, how do you explain game rules to an extraterrestrial who doesn’t know what a game is?
This exaggerated situation helped them get creative and think of new ways to describe something they had been working on for over two years. At the very least, it gave them something to laugh about after stressful meetings with investors.
Sometimes, in order to describe something effectively, you have to look at it with fresh eyes. Using the two types of description introduced in this chapter—process or product description—describe an everyday object to a visitor from another planet.
Remember, descriptions use specific, concise, and precise language. Your alien audience has traveled many light-years and perfected technologies well beyond human comprehension. In other words, do not talk down to your audience or you will be vaporized.
Consider the following items or processes to describe:
” Process: using an ATM, opening a door with a key, turning on a lamp
” Product: scissors, curtains, breath mints
Discussion
” First, define your purpose and audience so you can craft an effective message. How will that influence the narrative part of the description?
” How might the Known-New Contract help your process or product description?
” What potential problems might you encounter? How would you fix them?
Checklist for Definitions
Definition Basics
Is the definition placed so it doesn’t disrupt the flow of your content?
Have you selected the best type of definition for your purpose and audience?
Have you avoided using the word or phrase you’re explaining in the definition?
Supplemental
Have you tried describing your term by what it is not?
Have you considered if well-labeled visuals can clarify the definition?
Have you considered using hyperlinks in online documents to link to additional information?
Awareness
Are your definitions grammatically correct?
Have you considered the legal implications of your definitions?
Have you considered the ethical implications of your definitions?