TL;DR Expand acronyms or other short forms on first use.
When talking on a recorded medium (such as a bug tracker or mailing list) or to a large group always define acronyms before using them. You don’t know if all of your (present and future) audiences will know what you are talking about. In recorded mediums readers may not be able to find a definition for an acronym and when in groups people may not wish to speak up to ask for a definition. To ensure that everyone knows what you are talking about define your acronyms before using them.
Defining an acronym can mean spelling out the full word, or linking to an authoritative source. Links are especially useful when the acronym has become the name and the expansion has lost its original meaning. For example if I am talking about DNS I can link to the docs so that which DNS I am talking about is completely unambiguous. On the other hand if I am talking about something with a distinct name like Ripgrep (RG) it is sufficient to spell out the name and then later refer to it as RG. The key part of the definition is that it provides enough information to let current and future audiences figure out what you are referring to.
Why
Acronyms are Ambiguous
Just because you, and possibly the original target audience know what DNS you are talking about doesn’t mean that some later reader will assume the same thing. It takes almost no time to spell it out once at the top of a bug report or mailing list post.
Acronyms are not Memorable
Human brains aren’t great at remembering random sequences of characters. While “clever” acronyms like CAT might be easy to remember many are not. (Additionally the more memorable acronyms are often widely duplicated, believe it or not you aren’t the only team that managed to make their project spell “cat”)
Acronyms do not Convey Much Meaning
Full project names often convey some information about the project itself. Google Kubernetes Engine gives the reader a basic understanding of the project without having to look it up. This can save them time if they can now quickly decide that your writing isn’t relevant to them, or allow them to keep up in a conversation. Of course they will still need to look it up for a full understanding but even this basic information gives a good starting place.
Why Not
But this acronym is so ubiquitous that everyone will know it!
Go ahead then. I’m a sign, not a cop.
Some acronyms are unique, widely known and have become the name. For example if your audience is Network Engineers it is fairly safe that TCP will be understood to be the Transmission Control Protocol for many years to come. Expanding this acronym is likely superfluous, however keep in mind that it doesn’t hurt and expanding acronyms or linking to a definition is still a good habit to get into.
Top comments (0)