Deciding on whether to use technical vocabulary in your document comes down to answering two questions: ”Who’s reading your document?” and ”What are you trying to accomplish with your document?” Here’s how to answer those two questions (plus: How to write a great definition).
We’ve all tried to read documents that were so full of words we didn’t know that the document was, effectively, unreadable. We usually refer to those kinds of documents as ”jargon ridden.” Obviously, that’s not a good thing. But we are equally offended when we read documents that don’t use the terms that we’re used to – we feel those documents are either condescending (avoiding the ”hard words”) or written by someone who doesn’t know what they’re talking about.
Not surprisingly, then, one of the questions that people bring to Learning Tree’s Technical Writing course is how they should use ”technical words” in their documents. As usual in technical writing, the answer isn’t straightforward, though the process for figuring out what to do is. You have to know both your audience and your purpose in writing for them.
The first thing you must determine is what words your readers use. Any terms that your readers are familiar with don’t count as ”jargon” — it’s just part of your reader’s vocabulary. You want to use these words wherever your readers would use them and do that for two reasons.
The first reason is that this makes the document easier to understand for your readers. Any other terms that you might use will just require the reader to mentally translate your words into their vocabulary. The second reason is that using the reader’s vocabulary gives your document credibility. It shows that you know what you’re talking about — you’re using the ”insiders” vocabulary.
Of course, the danger here is that you’ll use the words incorrectly or inappropriately (i.e. where someone who uses the terms wouldn’t normally use them). As a result, it’s essential that you have your document reviewed by a subject manager expert to ensure that you are use the readers’ terms correctly. While using the technical vocabulary correctly gains credibility for your document, using the terms incorrectly will cost you credibility.
It’s easy to assume that the reverse of my previous advice is also true. If your audience doesn’t know the terms, then you shouldn’t use them. That’s generally true…but not always. The full answer requires looking at your purpose in writing for the reader.
If your document is designed as an entry point to a body of knowledge then part of what your document has to do is introduce readers to these terms. If, for example, the purpose of your document is to enable the audience to understand other documents in the field, then you need to provide your readers with the terms those other documents will use. If your document is going to quote or reference other documents that use these terms then it’s part of your document’s job to use those terms.
Of course, that means you’re going to have to define those terms. You’ve probably been told that you should do that in the first place that you use a new term. However, that assumes that your readers will read your document starting at the first page and carrying on to the last page — and that’s not what usually happens. You’ll be more useful to your readers if you define your terms in a glossary at the front of your document (typically called something like ”Terms Used in this Document”) or at the end (where the section is usually just called ”Glossary”).
There is one exception to that rule, if you have new terms that are only used in one section in your document, you can skip creating a glossary and define the term in that section.
A useful definition consists of two parts:
Part One: word(s) that the term you’re defining is similar. For this part of the definition, you should pick word(s) that your readers already know.
Part Two: the definition tells the reader how the term you’re defining is different from those words that the reader already knows.
This example assumes that readers know what the words ”HTML”, ”language”, and ”rules” mean. The example builds on that to tell the reader that, unlike HTML, XML is a way of defining new languages rather than a language itself:
XML: XML is a set of rules for defining a markup language (like HTML).
To be really useful, you’ll provide an example (drawn from the readers’ experience) that shows how the word is used:
We used XML to define a markup language to hold information about airplane flights.
As always, to communicate effectively, you have to know who your readers are. When it comes to technical jargon that means knowing what terms your reader already knows and then deciding on what you’re trying to do for your reader in your document. If you know the answers to those two questions, you know how to use jargon in your document.