Glossaries aid clarity
A glossary helps people to use documentation. 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 one word or many words. For an example, see the glossary of technical writing.
Usually, in a printed document, the glossary is at the end of the document. Usually, in a topic in online help, each term, or the first instance of each 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
For most technical documents, a glossary is necessary. Possibly, you think that the readers know the terms in the document. However, not all readers know all the terms. For example, on one project, our customer was sure that one term was not necessary in the glossary, because 'everyone will understand it'. But, after some time, 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 TechScribe's questions were about the differences between the terms. There were no differences. All the terms referred to the same thing. 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 an equivalent term. In the documentation, use only the preferred term.
In the glossary, explain the preferred term. Include the other alternative terms in the glossary, but do not explain the alternative terms. For each alternative 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