Stop Abbreviating!
A Plea to Technical Writers
If I could offer one piece of advice to anyone writing any kind of technical document — proposal, documentation, tutorial, even just a blog post — it would be this: stop inventing abbreviations.
Some abbreviations are useful shorthand for comprehension. For common technical jargon, the abbreviation may be far more familiar than the original words it stands for. No one talks about HyperText Markup Language or Cascading Style Sheets, we say HTML and CSS.
But for some reason which I have never understood, many writers feel moved to invent new abbreviations on the fly.
Imagine you are reading some technical documentation, something likely written by an engineer, and you encounter the following sentence:
For the POC, add the DB conf in a PR on BE.
If you are familiar with the language of software development, you might read “For the proof-of-concept, add the database configuration in a pull request on the back-end server.”
Someone with a different set of professional experiences might interpret it as “For the point of contact, add the dead body confessor in a per rectum on Belgium.”
Oh, come on, the author might say, everybody knows what I mean. Do they? How do you know? Do you personally know everyone who will be reading your document? Do they use the same technical jargon? Do they have the same educational background? Are they in the same field? Are they fluent in the same language? Do they read the same language, or are they relying on machine translation?
Even as a native-speaker of English, generally familiar with the technical domains I am reading about, I stumble over abbreviations like this every day. I can usually figure out the meaning, but it takes a moment of extra thought, enough to interrupt my flow.
Is it worth it, just to avoid typing a few more characters?
If you’re willing to spend hundreds of dollars on an ergonomic keyboard
and hundreds of hours tweaking your editor/
With that in mind, I offer a few simple rules to decide if and when it is a good idea to use an abbreviation or acronym in your technical writing:
Rule 1. If the abbreviation is well-known, to the point that it is used more often than the original word or phrase it stands for, then use the abbreviation.
If you’re unsure how common an abbreviation is,
try the Wikipedia test:
In your browser’s address bar, type
https:
followed by the abbreviation.
If you get to the Wikipedia page for that thing,
without any disambiguation
pages, then it's probably safe.
This test works reasonably well for common technical jargon:
It says we can always use abbreviations
for HTML
and CSS,
but not JavaScript (JS).
Rule 2. If the abbreviation is not well-known, use an abbreviation only if it will make the rest of the document easier to read.
Think of your reader’s brain like a cache. It can only hold a small amount of information, so you want to use that space for things that are likely to be needed again soon. Don’t waste that precious cache space just to skip a few characters. Save it for longer words or phrases, especially ones that will be repeated many times throughout your document.
Rule 3. Define the abbreviation the first time you use it, preferably near the beginning of the document. Spell out the complete word or phrase, followed by the abbreviation in parentheses:
It is a Simple Matter of Programming (SMOP).In HTML or Markdown
you can use the
<abbr> element
with a title attribute, like this:
The model is a <abbr title="Plain Old Java Object">POJO</abbr>.(Although POJO passes the Wikipedia test I suggested earlier, it is not well-known outside of Java programming.)
Rule 4. If none the previous rules matches, then do not use an abbreviation. Write out the complete word or phrase.
Finally, a summary flow chart:
Update July 23, 2023: I recently learned that healthcare organizations have recognized the risk of Dangerous Medical Abbreviations, to the point of publishing “Do Not Use” lists of commonly-mistaken terms. Their advice is basically the same as mine: Write out the full words, unless the abbreviation is a widely-used and documented standard.