Jargon in Technical Manuals

Jargon is a naturally occurring phenomenon in technical manuals. Here are some ideas on using jargon while catering to your audience.

The first rule of technical writing is to cater to your audience. Use jargon they will understand, or avoid it. This is not the same as eliminating jargon; it is convenient and can be appropriate if used judiciously and sparingly.

Using Jargon

If your audience already has a certain jargon vocabulary built into their lexicon, feel free to use it. Reader and writer will understand each other perfectly. You should consider whether every reader will be the expert you expect them to be. If even a minority of readers may not be up on the lingo, you need to cater to them some how. The best way is to include a glossary.  Not only does this help those who aren’t up on the particular jargon, it also ensures that your readers and you understand the same definition for various terms. This is especially important for acronyms.  Some industries are notorious for having identical acronyms meaning different things to different people. Communications is one of the worst. The same acronym can mean very different things for someone with a telephony background vs. someone with a computer networking background. These two fields merge with technologies like VoIP (Voice over Internet Protocol, a type of telephone technology), so it is important to define your terms.

Jargon can be very convenient. Rather than a one paragraph explanation every time you need to refer to a concept, you can just use a well known term unique to your industry. That’s what jargon is. Too much jargon can make your writing opaque, even to the initiated, so try to use jargon as little as possible whenever a clear explanation in plain English will suffice. It doesn’t hurt to define your terms and acronyms, as I did above with the term VoIP above, and highlight it (I’ve used italics in this case) so it stands out. I suggest italics rather than quotes because it keeps your text looking cleaner. This is especially important when you have to describe how to use software since quotes are used to explain exactly what the user should type into a field or command line.

Avoiding Jargon

There is nothing worse than jargon for those who aren’t used to it. If even a large minority of readers likely don’t have a background exposing them to the sort of jargon you would want to use in the manual, you should avoid it as far as is possible.

Jargon is convenient, so you may want to use a few carefully chosen industry- or product-specific terms for clarity and brevity, as long as they are well defined, either where they are used or in a glossary. It would be a mistake to use the jargon bandied about by the designers when the users don’t know or care about product design issues. I only recommend using unfamiliar jargon if you use a term repeatedly through the manual so it is worth the readers time to look up and understand the term. If you only need to use an unfamiliar term or acronym a few times across the manual, you might be better to fully spell it out and/or define it each time.