In searchable documentation, what function does a glossary serve?

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.

posted about 7 years ago

CC BY-SA 4.0

Mark Baker‭

4371 reputation 12 1104 744 58

I have several online Help projects for various products and only one currently uses a glossary. We made an exception to define words that are key to the product, which is a sister-product and built on the same code; so key terms had to be updated for the audience and use, and for that reason, we use a glossary which helps customers who use both products. I also think it is a good tool for keeping track of acronyms. Last, our users have a wide-range of technical expertise, so we have to cover the bases and define things that might seem obvious, but are hopefully helpful. I think polling your users is valuable as well as asking your trainers for their opinions.

posted about 7 years ago

CC BY-SA 3.0

Rachel‭

25 reputation 1 1 3 0

Do you really define every word every time you use it? That seems to me like it would be redundant and tedious. The first time I see a new word I want to know the definition. But I don't want to have to wade through the definition over and over again after that. That's where a glossary is useful. You define a word once. If a reader isn't familiar with the term, they look it up. In an on-line doc, you can give them an easy to click link. Then if they remember the definition they don't have to look it up again.

Even assuming we're not ridiculous about it and give the definition ten times in the same page, still, if your documentation is searchable, a user could jump in at any topic, so I presume you'd have to explain every term under every topic. I would think that could rapidly get out of hand. Like say you were writing documentation for this site. A topic like "how to upvote posts" would presumably require you to define "post", "upvote", "reputation", "privilege", maybe "user", probably several other terms. For the new user, this would all be valuable information. To the user who is already familiar with the general idea of the system, he'd quickly be saying, "yes, yes, get to the point".

I wouldn't grant that you shouldn't have industry-standard terms in your glossary. Well, I don't know what your product is, perhaps you can safely assume that any user is an expert in the field and knows all the standard terminology. But if not, it's not always easy to find the relevant definition of a technical term. Like if I tried to look up "post" in a dictionary or with Google, I'm sure I'd find lots of references to wooden posts like might hold up a fence, sending paper mail, recording accounting entries, to the prefix post- as in "after", etc. If I'm not familiar with the subject matter, I might have a hard time determining which definition is relevant.

posted about 7 years ago

CC BY-SA 3.0

Jay‭

1055 reputation 1 97 207 0

Some thoughts:

• I would ask the users instead of guessing whether they use the in-page popups. Do a (small) survey.
• Some users may not use the glossary because they are unaware of it but would if they knew. Ask in the survey.
• While I don't often use a glossary, the one time that I do it is usually indispensable.
• If you dispense with the glossary, make sure that all terms that are not easily found on the web are defined somewhere in the text of your documentation. Context may not explain them all equally well.
• A glossary might serve as a guideline for the writers (!) on how to use certain terms. If you don't have one, each writer might use a term differently.

posted about 7 years ago

CC BY-SA 3.0

System‭

3226 reputation 147 215 553 0