Glossaries aid clarity
A glossary helps people to use documentation effectively. It defines the technical terms and prevents ambiguity and confusion.
What is a glossary?
A glossary is an alphabetically arranged list of terms, along with a definition or explanation of each term. A term can be a single word or many words. For an example, see the glossary of technical writing terms.
In a printed document, the glossary typically is at the end of the document. In online help, the norm is for each term in a topic (or the first occurrence of a term) to have a popup that defines the term. Sometimes, a special Glossary tab exists which lists all terms in alphabetic order.
Why you need a glossary
All but the smallest of instructional documents should have a glossary. You may think that the terms in the document are well known to the expected audience. However, not all readers will be familiar with the terms. For example, on one project, our client insisted that one particular term should not be included, because 'everyone will understand it'. However, a few weeks later we were requested to put the term back into the glossary. One of their software users spoke English as a second language, and did not know the meaning of the term.
In one documentation project, source material contained many different terms such as 'base deck', 'base model deck', 'deck', 'model deck', and various other terms. Many of our questions early in the project dealt with clarifying the differences between these terms. There was no difference. All the terms were valid, and they all referred to the same thing. However, that can be confusing to readers, so, each term should have one meaning only, and different terms should not be used for the same thing.
One term, one meaning
If a one to one mapping between a term and a definition is the ideal, how do we deal with the other terms that mean the same thing?
First, choose the preferred term, that is, the term that will be used in the documentation (and consequently, the glossary). Use only that term in the documentation; never use other terms that mean the same thing.
In the glossary, define the preferred term. List all the other terms in the glossary, but do not define them. Instead, include a cross-reference to the preferred term. For example: DOS box see command prompt
Controlling the vocabulary in this way will help to make the document clear to the intended audience.
RSS feed