Creating Glossaries

I love glossaries. I use them all the time. If a book has a glossary, I'm always more willing to buy it. I highly recommend you include a glossary in your documentation. Your users will thank you and so will I.

'How do you make a glossary?" I hear you ask. This article provides some pointers.

What is a Glossary?

The American Heritage Dictionary of the English Language, Fourth Edition defines glossary as "A list of often difficult or specialized words with their definitions, often placed at the back of a book." A typical glossary entry includes a word or phrase and its definition(s). The entry may also include a cross reference to similar or related terms.

What terms you include in a glossary depends on:

the purpose of the document that will include the glossary
your target audience

For example, if you're writing an introductory text about computer graphics, you should include basic concepts like RGB, raster, and pixels. If you're writing a document for more advanced users, you could probably leave these terms out because you can safely assume your audience already knows them.

What to Include

When you're creating a glossary you should include:

New terms

Terms that you introduce within the document that your audience will not be familiar with.
Common terms used in a nonstandard way

Terms your audience knows but you are using in a different way. For example, most everyone understands that a topic is the subject of a article. In online help parlance, a topic is a single page of content that appears in the help file. If you were creating a glossary for online help, you would include "topic" as one of your terms.
Synonyms

Terms that mean the same thing. This is especially important if your document uses different terms than most people expect. For example, if your document is about online help and you use "info page" to mean topic, you should include both "info page" and "topic" in the glossary. You don't have to define both terms. You can either have one term defined as the other term or have one term cross referenced to the other.
Acronyms

Terms that are just a collection of letters, such as WWW or ANSI. When you create an entry for an acronym, you should use a "see XXXXX" cross reference to the complete term. For example, if WWW is an entry in your glossary, you should use "See World Wide Web" as your definition. Then, you must create an entry for World Wide Web and define it.

The format of the glossary will depend on personal choice and the media you're using. The key to any format is that you make the terms easily recognizable. You can do this by bolding them. Arranging terms alphabetically is a must. If you're creating a glossary for a web page, you might as well use the definition list tags: <dl /> to mark up the bounds of the list, <dt /> to mark up the term, and <dd /> to mark up the definition.

Wrap Up

That's all there is to creating a glossary. It's pretty easy. When you're creating your glossary always keep your audience in mind. A glossary is a tool your audience will use to learn your subject matter. You should design it for them. Plus, don't forget to check with any existing style guides your department may have or may be using.