Hacker News Reader

> 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>, 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</> 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.

This 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.

I think the google guide to technical writing recommends to write out acronyms once per chapter/section.

Should always be on first use, of course.

HTML has an entire tag for this. There is no good reason not to define those every time they appear.

A glossary is the most important document ANY project should have and maintain. Everything else is secondary.

Please explain what ANY expands to...

Nah, 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.

Perhaps in terms of the importance to effort ratio. How long does it really take to maintain an adequate glossary?

Agree 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.

Agree. A glossary is a way to introduce a domain piecemeal, without a long-form explanation.

I 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.

I'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.

I 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.