The one thing every tech writer hears early in a career is, “Avoid jargon in your writing.” Sage advice. But what is “jargon” really?
I did some research. The best definition that I’ve found comes from the Writing Center at the University of Alabama:
“Jargon is language that is specific to a field or trade . . . [consisting of] technical terms and common turns of phrase that . . . streamline communication with others in the field.”
I’ve unearthed some examples:
- “At the end of the day, it’s good ROI.” (From the business world)
- “Testing to assess the patient’s subclinical disease process uncovered occult blood in the stool.” (From medicine)
- “Pursuant to discovery of the client’s assets, the attorney filed for a motion to dismiss.” (From the legal realm)
People use jargon to talk to their peers–doctors to doctors, lawyers to lawyers, Californians to Californians. Jargon has its place. But technical documentation, rather than speaking to people of the same mind, must bridge the gap between people from seemingly different planets: the product’s developers and its users.
So, how can you tell if your docs are jumbled with jargon? Look for these traits:
- Word bloat. People, especially the SMEs we work with, love to make short words long. (I’m not sure why. Maybe it gives them time to form their next thought.) So if you see words in your text like “methodologies” where “methods” would do, amputate the offending appendages.
- Abstract nouns. What are those? I like Wiktionary’s definition: “[An abstract noun is] a noun that denotes an idea, emotion, feeling, quality, or other abstract intangible concept, as opposed to a concrete item, or a physical object.”A great example is “ROI,” return on investment. It’s business jargon for “we think we’ll make more money than we’ll lose on this endeavor, but nobody’s really done the math yet.”
- Euphemisms. Here’s a good one: About five years ago people started calling “bugs” in products “exceptions.” I get the reason—not every unexpected result in an application is a problem, or “bug”—but take note. If you see words like “features” in your writing where “functions” or another neutral term would work, stop liking the product you’re writing about so much.
- Uncommon words. For example, to anyone who isn’t a lawyer, the word “pursuant” (see above) rankles.
Jargon is everywhere, like bedbugs, or Kim Kardashian. That said, you don’t have to use it in your work—even if someone tells you that at the end of the day, it’s just good ROI.