: 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

Vote Up Vote Down

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.

(0)

Vote Up Vote Down

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.

(0)

Vote Up Vote Down

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.

(0)