: 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

@Annie587

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)

Login to post a comment!