Post History

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

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

In terms of providing definitions for general terms, I would say that glossaries are pointless in online documentation. User can easily search for any term they do not understand.

If there are terms that refer to concepts that you describe in your documentation, I would say that it is far more valuable to link them to a topic that describes that concept than to link them to a glossary that merely defines the term. This is something that a book cannot do, so a glossary entry provides a poor substitute for linking to a full treatment of the subject. But online you can link to a full article on the subject, and that is far more valuable than just linking to a definition.

There is also an SEO downside to publishing a glossary, which is that glossaries are keyword rich, which means that they can rank high in search engine rankings. The problem with this is that glossary entries are generally not much use to searchers. They want the main page on the task, not a glossary definition. So creating a page with a lot of search bait on it just creates a distraction that potentially pushes the main page down the rankings and makes your content harder to find.

However, there is another function for a glossary that you may want to consider. Glossaries are sometimes uses to define local definitions for common words that you are using in a specialized way. That is, they provide local definitions that override the common definition or the word. This mostly occurs in conceptual material where you are trying to explain a new concept or approach or a new technology where the distinctions made by common technology do not apply and you need to make subtle adjustments to the way you use words in order to get your point across. In these cases, a glossary is still important, though there is a very real issue about whether your readers will actually use them or not. As readers become more habituated to online information is becomes less safe to assume that they look for or use paper-world devices such as glossaries or indexes.

Original score: 5