Technical Writing and Jargon

by Bradley Nice, Content Manager at ClickHelp — all-in-one help authoring tool

We all came across the documents that were so full of unfamiliar words that the document was unreadable. I call such kinds of documents “jargon-bloated.” That’s something that influences users’ attitudes in a wrong way. But, on the other hand, we are equally perplexed when we read documents without the terms that we’re used to — we feel those documents are either condescending or written by someone who doesn’t know what they’re talking about.

I am talking about jargon. It has several meanings. Most of us think of the word “jargon” in a negative sense. It’s something we’re supposed to avoid in our writing at all costs. By jargon we mean:

  1. Confused unintelligible language;
  2. Obscure and often pretentious language marked by circumlocutions and long words;
  3. The technical terminology of a special activity or group.

We are interested in variant number three since it is connected with technical writing. Here jargon is simply a word or phrase that requires specific knowledge for the reader to understand. As a writer, be sure to know the audience you’re trying to reach and become familiar with its linguistic niche.

So, How to Use Jargon Reasonably?

First, you must determine what words your readers use: any terms that are familiar to your users don’t count as “jargon.” Using these words wherever your readers would use them makes the document easier to understand, and it gives your document credibility. It shows that you know what you’re talking about using the “insiders” vocabulary.

The hidden hazard here is that you may use the words incorrectly or inappropriately. That’s why it’s essential to give your document for review by a subject manager expert to ensure that you are using the readers’ terms correctly.

If the audience doesn’t know the terms, then don’t use them. But sometimes, the purpose of writing for the reader demands to deviate from this rule. For example, if your document is an entry point to a body of knowledge, then the part of your document has to introduce readers to these terms. That means you’ll need to define those terms. For that, it is more beneficial to define your terms in a glossary at the front or at the end of your document. If there are not many words to create a glossary, define the term in that section. To be really useful — provide an example from the readers’ experience that shows how the word is used.

When it comes to technical jargon to communicate effectively means knowing what terms your reader already knows and then deciding on what you’re trying to do for your reader in your document.

Certainly, there are things to avoid when using jargon:

  • Use jargon only with necessary technical terms;
  • Don’t use technical terms inappropriately;
  • Using jargon to communicate a basic ordinary message is a huge mistake.

If you are still not sure how and where to use jargon, you can use special tools, like Jargon Grader. It can help you identify and eliminate jargon that clogs your writing.

Jargon is often considered a bad thing. But technical jargon is helpful for members of a professional group to communicate with each other. It acts as a kind of shortcut, allowing them to express specialist concepts. But when technical jargon is used in writing to people unfamiliar with it, you can encounter some problems.

Common words used with a specific meaning that the writer does not make clear are particularly dangerous. Readers may completely misunderstand the message. But technical jargon should be included in the documentation for the public (so long as it is well explained). Because it makes words and phrases from technical jargon more widely used, it is impossible to replace such words or phrases entirely with plain-English translations. So, while you should be cautious about vocabulary, it does serve a purpose. The trick is knowing when to use it and when to avoid it.

Have a nice day!

Bradley Nice, Content Manager at ClickHelp.com — best online documentation tool for SaaS vendors

Content Manager at https://medium.com/level-up-web 👈. I write about web design, web development and technical writing. Follow me on Twitter and Facebook