8

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?

6

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.
  • I particularly like the idea of it being a guideline for writers although you may have a writers manual for that. – Joe Sep 13 '17 at 8:53
5

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.

  • SEO is a good point that I hadn't considered. On your last paragraph, that's what I was talking about when I said " terms that are specific to, or different in, our product". Is a glossary still helpful, in addition to the actual in-context doc? How do we know? – Monica Cellio Sep 11 '17 at 0:21
  • If you describe the concept in-context where it is mentioned, then I see no point in a glossary. Online documentation is read random access -- actually almost all tech pubs are read that way. No one sits down to familiarize themselves with the entire terminology set at one sitting. By the same token, since the docs are read random access, you can't just describe the concept the first time it is used. Any time could be the first time for the reader. That is why I prefer linking to a full article on the concept, rather than a glossary or describing inline. – Mark Baker Sep 11 '17 at 2:46
  • 1
    I'm not sure you need a glossary per se, but linking key terms (wherever used - at least per page) to explanatory text/whatever is a good idea. If you use a term a lot and I search for it on your site (site:yoursite term), I'll get a bunch of hits which are just uses of the term with the defining reference buried in the middle. It gets even worse if the term can be a part of other words or phrases or has different meanings in different contexts. – Joe Sep 13 '17 at 9:13
  • 1
    @Joe And that uncertainty about which page the search will return first is exactly why thorough linking is so important. It help the reader get the last mile to the topic they really need. – Mark Baker Sep 13 '17 at 11:20
1

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.

  • We don't fully explain a term every time it's used; as you say, that would be burdensome. We do provide pretty good cross-linking among the conceptual doc for a thing (or set of highly-related things) and the specific functions, system tables, configuration parameters, etc that interact with it. I'm wondering if we should do more of that and ditch the glossary, do more of that (because it's good regardless) and keep the glossary, or what. – Monica Cellio Sep 11 '17 at 18:44
  • My question was meant rhetorically. I suppose if the nature of your system is that there is a function corresponding to every term, so that to explain the function is to explain the term and vice versa, than in a sense you are integrating the glossary into the body of the documentation. – Jay Sep 11 '17 at 19:04
  • Not 1:1 by any means, but there are linkages. – Monica Cellio Sep 11 '17 at 19:07
1

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.

1

I consider a glossary very helpful despite linking to term definitions from documentation articles. The glossary acts as a word list restricted to the "important" words used in your software.

Ueers may want to look up such words on many different occasions:

  • when reading about them in a documentation article
  • when reading about them in the application's UI
  • when reading about them in secondary sources referring to the software (e.g. a Stack Exchange post ...)

Only in the first case is linking quite reliably helpful.

Full-text search is not that useful in that respect, either:

  • Users want to find the definition of the term, not all articles that mention it.
  • Users may not know the name of a concept. Scanning a list of glossary terms for likely candidates is probably feasible, as opposed to scanning the list of all occurring words.

Moreover, note that at least for definitions of application-specific terms that you would write anyway, maintenance cost for the glossary is practically zero, as it would just mean to flag articles for inclusion in a glossary. The glossary itself, i.e. an ordered list of the terms, would of course be generated automatically.

Lastly, a glossary of such terms can have beneficial side-effects on the development side, as well (and the requirement to make it publicly available can be the crucial factor to create the discipline to actually fill and update it). Beneficial effects include:

  • Defining special terms cannot be forgotten as easily.
  • Different subteams can steer clear from creating overlapping or otherwise conflicting terminology in different modules.
  • Translators have a guideline which terms to pay attention to and to distinguish from each other.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.