AIANYF: Acronyms & Initialisms Are Not Your Friends
This post is part of a writing advice series. Writing clearly is one of the most important — and overlooked — skills.
Technologists love themselves some acronyms and initialisms (for the sake of readability, we’ll just use “acronyms” to mean both). Maybe it’s because tend to give things very unwieldy names. Who would want to say “hypertext transport protocol” over and over when you can say “http” instead? But acronyms can be confusing when they’re unfamiliar to your reader. Err on the side of explaining, even if you don’t think you need to.
Always. Be. Expanding.
You’ve probably been told to expand acronyms the first time you use them. For example, you might write “hypertext transport protocol (http)”. That is good advice. Follow it. I am no longer convinced that it is sufficient advice, though.
Open source projects are full of jargon, be it unique acronyms, arbitrarily-named services, etc. If you’re lucky, new contributors are coming in. Can they understand your communication and documentation?
Until recently, I often used “FPgM” to refer to my “Fedora Program Manager” title. The role has been around for 15 years, it should be well-known, right? Then one day I was talking to a contributor who had some experience in the Fedora community. They had no idea what I said when I meant “FPgM”. Well, crap. How many other people were completely lost and never told me?
I’ve come to the view that I should avoid acronyms most of the time. What good is saving myself a few keystrokes if my reader doesn’t know what I mean?
When to use them
Acronyms aren’t always the enemy. It all depends on the context. Think about what you can reasonably assume your reader knows. Is it reasonable for them to know what it means? (Be careful. You’ll probably assume too much!) If so, then you can use it.
Sometimes it doesn’t matter if the reader knows what the acronym means. If you’re giving instructions on how to register for a website, you might tell the reader to go to “http://example.com”. Now is not the time to explain what “http” stands for. It doesn’t matter in the context of what you’re trying to communicate. If it stood for “hotel towels: totally plush”, that wouldn’t change anything.
A combination of the previous two scenarios is acronyms that are common knowledge outside of a specific domain. Laser stopped being an acronym (“light amplification by stimulated emission of radiation”) and became a word in its own right. The same goes for “scuba”. In fact, expanding those acronyms on first use might cause confusion.
Tips for clarity
In general, you have to make a judgement call about when to use an acronym. In most cases, though, you probably don’t need to. Invest a few extra key strokes and spell out what you’re talking about. When you do decide to use an acronym:
- Expand it the first time you use it
- Add a link to more information the first time you use it
- Set up an “acronym jar” that you contribute to every time you use an unfamiliar acronym
This post’s featured photo by Aaron Burden on Unsplash.
