4 ms·
One of my pet peeves while reading technical documents is coming across acronyms that have not been introduced to the reader yet. When this happens over and ov
by susam 3y ago
One of my pet peeves while reading technical documents is coming across acronyms that have not been introduced to the reader yet. When this happens over and over again across several documents of a project and people working on the project change over years, sometimes we end up in a situation where nobody can tell anymore what a particular acronym expands to.
In fact, more than once, I have seen the bizarre situation where a team is responsible for developing and maintaining some service known by the name, say, ABC, but nobody in the team knows what ABC really expands to. In such instances, in order to avoid choosing a new name and updating all related documentation etc., the only recourse is to treat ABC as a proper noun and move on.
Fictitious example: To obtain an access token for CDIS, first go to DMC at <https://dsc.prod.example.com https://dsc.prod.example.com>, click on the entry for "CDIS" on the left sidebar, click "Generate Access Token", and copy the token.
What I would like to read instead: To obtain an access token for Customer Data Indexing Service (CDIS), first go to Data Management Console (DMC) at <https://dsc.prod.example.com https://dsc.prod.example.com>, click on the entry for "CDIS" on the left sidebar, click "Generate Access Token", and copy the token.
- HeavyStorm 3y agoA glossary is the most important document ANY project should have and maintain. Everything else is secondary.
- drittich 3y agoPlease explain what ANY expands to...
- lawn 3y agoNah, it doesn't pass the sniff test. Is it more important than a list of critical bugs? A document explaining how a developer can get the application up and running? A document detailing how the production server is setup and how to gain access? When you think about it, lots and lots of projects manage without any kind of glossary but would go up in flames without some kinds of documents.
- mike-the-mikado 3y agoPerhaps in terms of the importance to effort ratio. How long does it really take to maintain an adequate glossary?
- liamwire 3y agoAgree strongly. I think an even more insidious version of the parent comment is when common nouns that have specific meaning in a given context are used as such, without it being explicitly called out.
- hcarvalhoalves 3y agoAgree. A glossary is a way to introduce a domain piecemeal, without a long-form explanation.
- nuancebydefault 3y agoI find glossaries quite often not very useful because they tend to get copy/pasted across documents and the acronyms are often just expanded without giving the correct meaning in the context of that document. I'd rather have it fully spelled at first usage, with the acronym in brackets. This enforces a more natural order of writing and reading the document and provides a better context.
- wildrhythms 3y agoI see this happen in non-technical spaces too... product managers using project-specific acronyms and codenames in front of an audience of new people. I can't tell if it's some form of narcissistic gatekeeping, or just lack of mindfulness and deep entrenchment in the project for too long. I am so hyper conscious of this that I will stop meetings to ask the presenter to define the terms.
- andsoitis 3y ago> What I would like to read instead: To obtain an access token for Customer Data Indexing Service (CDIS), first go to Data Management Console (DMC) at <https://dsc.prod.example.com https://dsc.prod.example.com>, click on the entry for "CDIS" on the left sidebar, click "Generate Access Token", and copy the token. Even better: <a href="https://dsc.prod.ex.com/gettoken">Get</> https://dsc.prod.ex.com/gettoken">Get</> an access token from the Data Management Console (DMC) to access the Customer Data Indexing Service (CDIS). The best documentation is no documentation. This documentation is there because the two systems aren't linked and that is the real issue. If there isn't budget to do the integration, then better is have the hyperlink to DMC on the log in page of the CDIS, which can then avoid the separate documentation altogether.
- brainzap 3y agoI think the google guide to technical writing recommends to write out acronyms once per chapter/section.
- _tom_ 3y agoShould always be on first use, of course.
- tpoacher 3y agoI'm always tempted to go passive-aggressive and misinterpret the acronym. I don't, but I'm tempted to. E.g. "Couldn't we simply write an email to the Computer, Data, and Information Services department for the access token? This keeps a paper trail, and explains why you need Digital Media Credentials in the first place." I'm someone who's jumped from Medicine to CompSci. Each field uses their own obscure acronyms that highly intersect. I'll spare you the embarrassment that comes from someone making a "Pro Rectum" request.
- vundercind 3y agoHTML has an entire tag for this. There is no good reason not to define those every time they appear.
- _tom_ 3y agoThis is a related to my number one problem with technical writing or text books: forward references. "Let's talk all about a topic we will define three chapters from now" Learning about things with undefined terms, concepts and acronyms is much harder and may require multiple passes over the material. It's a hard part of writing a linear book about a topic that's probably a graph, but good writers manage it. Bad writers just leave their readers confused.