: Re: 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

@Rambettina586

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)

Login to post a comment!