In searchable documentation, what function does a glossary serve?
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?
4 answers
You are accessing this answer with a direct link, so it's being shown above all other answers regardless of its score. You can return to the normal view.
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.
This post was sourced from https://writers.stackexchange.com/a/30176. It is licensed under CC BY-SA 3.0.
0 comment threads
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.
This post was sourced from https://writers.stackexchange.com/a/30174. It is licensed under CC BY-SA 3.0.
0 comment threads
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.
This post was sourced from https://writers.stackexchange.com/a/30197. It is licensed under CC BY-SA 3.0.
0 comment threads
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.
0 comment threads
0 comment threads