How to Write Glossaries

Glossaries can be quite difficult to write, mainly because some definitions require so much research. While many definitions can be found online, others cannot. For these, you will have to read standards, Requests for Comments (RFCs), and books—a lot of work for a three- or four-line definition!

Do not ask the subject-matter experts (SMEs) for glossary definitions. First, they will ask you why you want to define that particular term; second, they will try to persuade you that you don't need to define the term; third, they will tell you that everyone knows what the term means. Finally, after you've politely convinced them that you are going to define it whether they like it or not, they will be unable to crystallize all their knowledge about the term into a pithy definition.

It is tempting to copy and paste a definition from an online dictionary into your glossary (who'll know?), but please don't. Aside from the fact that it is very, very, very bad to plagiarize, some of those definitions are not well written and some are even wrong. It is better to collect as many definitions as you can and rewrite them in your own words.

While there are plenty of online dictionaries that you can access one at a time, you can find a portal for most of them at OneLook Dictionaries and Glossaries. You won't find definitions for all your terms here, but it's a great place to start.

Roughly five to ten percent of your terms will not be found in the online dictionaries. For these, you will have to intensify your research. Start with search engines such as Google. These will often return RFCs (Request for Comments) and other preliminary versions of standards. If your corporate library keeps standards in its collection, go and get a copy of the standard that replaced the RFC. If the library does not keep standards, or if the RFC has not yet been formalized into a standard, then download the RFC. You can also search for RFCs at the RFC Index Search Engine and you can order standards from IHS Global.

Standards and RFCs are not easy to read. They tend to assume a lot of knowledge on the part of the reader, and they are often based on technologies that are described in other standards. Rather than finding everything in one standard, you might have to read several other standards just to understand the first!

Occasionally, you will have to write definitions for terms that are proprietary to your company. Be careful here. Many SMEs believe that a term is proprietary even when it is not. This problem is more likely to occur when your department is working on a product that is based on a technology or standard that is still in the development phase. Before deciding whether or not a term is proprietary, search for the term in an online version of the most current standard. If it is there, it is not proprietary. If it is not in the standard, however, and you are still uncertain, ask the system architect, the product manager, or the project manager, or anyone who has a big-picture view of the project.

As you have probably by now determined, creating a glossary requires a lot of effort, which of course translates into time and money. To save time on future projects and also to ensure that definitions in one document are identical to those in other company documents, consider creating a company glossary. This is simply a file in which you save all the definitions you create. As new projects are developed, you will add new terms to the company glossary, but you will also be able to reuse many of the definitions that are already there. A company glossary not only saves you time, but it also helps new-hires, who usually spend the first few weeks of employment floundering in a sea of mystifying acronyms.

Guidelines For Writing a Glossary
Keywords (terms, acronyms, and abbreviations used in your document) must appear in alphabetical order. Keywords that begin with numbers should be positioned in the glossary as though the number were written as a word. Thus, "10Base-T," for example, would be placed after "TCP/IP" and before "time offset."

Capitalize only those words—like Ethernet for example—that are proprietary or that are otherwise intended to be capitalized.

For acronyms and abbreviations, do not provide the definition. Instead, expand the acronym or abbreviation to the full term, and provide a reference to the full term and definition. For example:

    AAA
      See authentication, authorization, and accounting.

    authentication, authorization, and accounting

      A service that verifies the identity of users who request access to a network, and determines blah blah blah.

Do not restate the term in the definition. Avoid definitions like "A [term] is a word that describes what happens when . . . ".

Keep the definitions short.

It is much easier to define a noun than a verb. If you are trying to define a verb, consider changing it to a noun. For example, rather than trying to define "allocate," define "allocation" instead.

Checking Your Glossary
As with all of the documents you write, once your glossary is complete, it must be sent to the SME to be tested for technical accuracy. The difficulty here is that one SME will not know if all of your terms are correct. You must therefore send your glossary to more than one SME, and this creates another problem: how will you know which terms were not verified?

To solve this problem, first of all, decide that you will send the glossary to only one SME at a time. In other words, do not send your glossary to more than one SME because you will discover, when you get the glossaries back, that they have all verified the same terms, thus creating an annoying duplication of effort. So, you will ask one SME to do an initial check, then you will ask another SME to check the remaining terms, and so on, until all the terms have been verified.

Now, in my experience, SMEs hate to admit when they don't know something and, if you are not careful, your returned glossaries will give you the impression that all the definitions are correct, even though some of them are not. To ensure that all terms are eventually verified, tell the SMEs that the returned glossaries must clearly indicate the definitions they were able to check and the definitions they were unable to check. Here are the instructions that I give my SMEs (I write them at the top of the glossary):

Please check this glossary according to the following guidelines:
  1. If a definition is correct, put a checkmark beside it.
  2. If a definition is wrong, but you can fix it easily, make a note of the corrections.
  3. If a definition is wrong, but it would take you too long to fix it, put an X beside it.
  4. If you do not know whether a definition is right or wrong, leave it blank.

When the glossary comes back, you will easily see which definitions have not been verified. You can then send these definitions (and only these definitions) to the next SME, and so on, until all the definitions have been checked.

Google
Webwww.docsymmetry.com