Glossaries aid clarity
A glossary helps people to use documentation effectively. A glossary explains each technical term and prevents confusion.
What is a glossary?
A glossary is an alphabetically sorted list of terms, with a definition or an explanation of each term. A term can be a single word or many words. For an example, see the glossary of technical writing terms.
Usually, in a printed document, the glossary is at the end of the document. Usually, in online help, each term in a topic, or the first instance of a term, has a pop-up window that explains the term. Sometimes, a special Glossary tab lists all the terms in alphabetic order.
Why you need a glossary
Most technical documents require a glossary. Possibly, you think that the terms in the document are well known to the readers. However, not all readers will know the terms. For example, on one project, our client was sure that one particular term was not necessary in the glossary, because 'everyone will understand it'. However, some weeks later, we were asked to put the term back into the glossary. One of their software users spoke English as a second language, and he did not know the meaning of the term.
In one documentation project, source material contained terms such as 'base deck', 'base model deck', 'deck', 'model deck', and other combinations. Early in the project, many of our questions were about the differences between the terms. There were no differences. All the terms were valid, and they all referred to the same thing. However, readers can be confused when different terms mean the same thing. Ideally, each term has one meaning only, and different terms are not used for the same thing.
One term, one meaning
If one term has only one meaning, how do you manage the other terms that mean the same thing?
First, choose a preferred term. A preferred term is a term that is used in preference to another equivalent term. In the documentation, use only the preferred term.
In the glossary, explain the preferred term. Include the other terms in the glossary, but do not explain them. For each term, include a cross-reference to the preferred term. For example: DOS box see command prompt.
Use terms consistently to make the documentation as clear as possible to the readers.
RSS feed