The Jargon Bargain

A colleague recently sent me this little quiz that poses the test taker a series of terms. For each term, you answer whether it is a reference to some big data technology or to a Pokemon thing.

If you decide to take the quiz, be sure to keep score yourself because it's a pretty simple form and won't do it for you. But it does make a good point.

Take the Big Data Pokemon Quiz

The quiz is goofy and funny but it makes a point. If you don't store data in Hadoop or catch Crebases while playing Pokemon, you probably don't know which is big data and which is anime. The words are jargon.

Jargon isn't bad. Jargon makes it possible for specialists to fire off quick notes without explaining every detail. For those who deal with them daily, reading or writing, "I need your TPS about the DoD POC before COB," is easy. For them, it's easier than reading or writing, "I need your testing procedure specification about the Department of Defense proof of concept before the close of business." In my own field, the phrase "high cardinality" might be bandied about casually, leaving a newcomer in the dust. But that's OK if it's an A-and-B conversation and both A and B know what high cardinality means. If you're writing for a general audience, though, think twice.

Jargon can lock people out. If your goal is to include only other specialists, jargon on. People who landed on the page by accident intuit whether they are the page's intended audience by whether they understand the jargon. If I land on a page and don't understand any of it, odds are, it was written for a specialist rather than me.

But if your intention is to explain to people things that they need to know but probably don't, jargon is rocky terrain. It will slow down your users, who are like travelers. If you need to use jargon, do so sparingly. Link to a glossary or to a quick explanation. Best of all, use tooltips that appear when people put their mouse cursor over the jargony word. One time, I came across a topic for business users that used, without explanation, the word asynchronous to describe a process. "This process is asynchronous with the previous one." Do you know what that means? I know because I work with web development. But how many business users know what it means? How many will be able to intuit the meaning easily? This particular term is hard because, in software development, it's used differently to its standard English meaning. It would have been better to write, "You must not start this step until the previous one finishes." The first wording is likely to cause head-scratching whereas the second wording instructs the user. Neither tells the user that processes are asynchronous if the computer is able to run them at the same time but mustn't. In the first case, that might have helped clarify. In the second one, it's not needed because instead, we told the user what he or she really needs to know. Guess which approach I prefer.

So with jargon, we find ourselves striking a balance based on our audience. If our audience is general in nature, we should use jargon sparingly. We should use any particular bit of jargon only after introducing and explaining it. The same goes for abbreviations. On the other hand, if I am a writing for an audience in my field, I'll save people headaches by using jargon. As with so many things in life and in writing, the key is to know your audience.

Hints for dealing with jargon:

Give preference to easily understood words. Use more difficult words only when necessary. Use industry-specific jargon only when you must, unless your audience knows the term. Use company-specific or product-specific jargon only when absolutely necessary.

Don't coin a new term unless you must. There is often an existing, understood word for any particular thing. Use that. Your engineers and product managers often want to coin a new term because they've built something new relative to your product. The documentation isn't where they get to show off their accomplishments. It's where you explain things to users.

Don't use internal names externally. Your company might have an internal name for a thing. If that name appears in the user interface or on the product itself, you should use it. But if the name doesn't appear on the product and users won't likely understand it immediately, don't use it. That's coining a new term, as far as your user can tell. Maybe your programmers have come up with a nifty new kind of drop-down menu. But when you need to tell a user to select an option from it, just call it the "drop-down menu".

All this boils down to one piece of advice: When you can, use plain words.

This brings me to a book recommendation. It's one of my favorite books: Plain Words, by Sir Ernest Gowers.

Sir Ernest wrote the book to help the British civil service better communicate with the British public. To this day, British government documents and websites run circles around the US government's, when it comes to clarity and ease of reading. The book is written in bite-sized pieces so it makes seriously good bathroom or bedtime reading. I read or reread a passage or two every few days to help keep the concepts in mind.

That said, again, remember: jargon is not the enemy. It is a powerful tool. Don't spill it all over the page. Use jargon for good by using it deliberately.

This post was originally published on api-ambassador.ghost.io