Post History

Source: https://writers.stackexchange.com/q/30168
License name: CC BY-SA 3.0
License URL: https://creativecommons.org/licenses/by-sa/3.0/

I work (with a team) on a large documentation set for a complex software product. We publish HTML and have built-in search (plus, of course, there's Google).

The doc set has a glossary, which predates most team members and has accumulated a lot of entries over time. It currently contains the following kinds of entries:

- General industry terms with no content specific to our product. We are currently pruning these out because we all agree that Wikipedia does general CS (etc) well and why should we try to duplicate that? (There is a small maintenance cost to keeping them.)

- Longer explanations of terms that are specific to, or different in, our product. The same information is also presented in the "natural" places in the doc set -- wherever you'd need to talk about that concept anyway, we talk about it in context. I see no point in making people interrupt their flow of reading to go visit a glossary entry, even if it's an in-page pop-up.

- Terse explanations of terms that are specific to, or different in, our product. The better ones contain links to the places in the doc set where they're talked about more.

While reviewing our glossary for terms that should obviously be pruned (that first group), I started to wonder about the bigger question: is having a glossary in this doc set useful _at all_? Our analytics tell us that almost nobody goes to the glossary to look up particular topics, but it looks like we aren't separately measuring those in-page popups so people might be using those. Or not. We do see that people use our search to look up terms, and they usually go to the places in the doc that talk about them in context, not the glossary entries.

I've seen other online documentation sets that have glossaries; it's not just us. Are there established best practices for glossaries specifically for online, searchable documentation? What use cases do glossaries support, that we should be mindful of and avoid breaking? Or are glossaries basically irrelevant and instead of pruning it we should be thinking of getting rid of it entirely?

Original score: 8