I want to talk about the words we use. As technical communicators, words are our primary method of communicating with our audience. Whether we create manuals, online help, tooltips, or UI labels. Even a video explaining a new feature is a combination of pictures and spoken words.
One of the primary pieces of advice for technical communicators is packed into two words: avoid jargon. A slightly longer version would be: don’t confuse your readers.
Confusing people is the opposite of what we’re supposed to do. If we perform our core function adequately, we remove confusion, instruct our readers, answer their questions, solve their problems, and help them do their jobs.
The ironic thing is that it’s not often clear what is meant by “jargon.” One person’s jargon is another’s lingua franca.
Sorry, that was jargon right there.
A simple definition of jargon is any term our readers don’t understand. But this definition isn’t complete until we understand our audience and build a vocabulary that we can expect them to recognize. If you document a product used by expert mathematicians with multiple PhDs, then you don’t have to worry about using complex mathematical terms throughout your documentation. Similarly, if you document a sports tracking application, you can assume your audience won’t be confused by sports metaphors.
But if your audience isn’t so narrowly-defined, if it includes people of multiple levels of expertise and familiarity with the subject, then you need to use more simplified terms, and add more explanations.
On the other hand, there’s a danger in oversimplifying our language. Try to explain any piece of business software using one-syllable words, and you’ll end up with documentation that’s vague and confusing. Morten Just created a text editor that only accepts the 1,000 most common words in the English language. I tested this by trying to rewrite what I thought was a simple blog post, and I ran into problems almost immediately. I couldn’t refer to someone as a “computer programmer.” I couldn’t call myself a “technical communicator.” The best I came up with was “computer talker person” and “computer explain writer,” respectively, and those are far from obvious! “Computer explain writer” doesn’t begin to cover what technical communicators do, since our work is not limited to computers, or even writing.
By oversimplifying, we risk losing meaning. Not that we should create documentation that’s nuanced and subtle; in fact, those things are a nightmare when it’s time to localize our content. But we do want to use the right word in the right place, for the right reason.
Which is maddeningly vague. Because if we make the documentation too complicated, we’ll start losing reader attention. If no one wants to have to read the documentation, they certainly don’t want to have to read the documentation with a dictionary at the ready. We can provide a comprehensive glossary and pepper our documentation with links and plenty of context, but a mass of unfamiliar terms will discourage even the most motivated reader.
Our job as technical communicators is to make complex concepts…well, maybe not simple, but certainly less complex, and easy to understand for our audience.
It always comes back to this: know your audience. You don’t need to know every one of their names, their family members, and their secret origin stories, but you do need to have a basic understanding of who they are and why they’re using your product. Is your product designed for business users? What kind? Sales people? Product managers? Customer support?
Customer support agents, for example, will be familiar with the concepts of “tickets” and “root cause analysis.” Someone in marketing might not be familiar with that, but “cost-per-impression” and “churn rate” are terms they use every day.
Over time, we run the risk of becoming complacent about terminology. Since we, as technical communicators, often work with multiple areas of our businesses, we’re likely to be exposed to more jargon than most of our coworkers. The more we learn, the more we start to accept those terms and stop questioning what they are, what they mean, and whether we should use them in this particular piece of documentation. We forget to find better ways to express the concepts, because it takes work to simplify complex concepts, and no one willingly adds more work for ourselves.
But, ultimately, we have to do this for our customers. For example, when I worked for a data analysis company we assumed that our main users were data scientists. Based on that, we further assumed that they would have at least a working knowledge of statistics.
During a customer training session, we learned we were wrong. Of the 24 customers in the training, only 2 of them were comfortable with the terminology we were using. For the rest, it was either all new to them or something they had seen years ago in a mostly-forgotten college course. And these were very smart people, experts in very technical fields. But they weren’t statisticians. In this case, the quick fix was to add explanations and examples to the documentation and review the concepts during training; but this eventually led to changes to the product, too.
That’s why we must keep asking questions, and pay attention to the context in which jargon is used. Find ways to continually learn more about your customers. You can’t interview every one of your readers and figure out the limits of their vocabulary, but you can interview people who do talk to your customers more often.
Talk to your customer support team. Review some tickets to see what terms customers use when reporting issues and asking questions. Do they talk about your product the same way you do in the documentation, or do they use completely different words? And if they use different words, is there any consistency among tickets filed by different customers? Even more important, find out how your support team explains your product to customers. And start using the same terminology!
On the plus side, this effort can lead to a great way to reduce customer confusion: create a shared glossary, with input from your coworkers, and make sure that everyone who talks to customers follows the glossary. It might seem pedantic, but consistent terminology helps your customers learn to use your product by letting them learn to identify and categorize the ideas, interfaces, and activities that are new to them.
Your training team is also a good resource. If you aren’t already working with them, take a look at their training materials to see what terminology they use. Ask them how they introduce and explain concepts, and about typical questions that come up during customer training.
By learning more about your customers, and about how your customer-facing teams communicate, you can help shape the consistent user experience across all of the customer-facing teams. When your customers feel less confused and more comfortable with your products, they are more willing to keep using (and paying for!) them.
