How to Awake Your Glossary From Zombie Mode

When we look at requirements documents that are new to us, we often need some help on terms and abbreviations. Creating a glossary to explain these imporant domain terms and abbreviations is a fine idea. It helps new team members to get going, improves the readability of a requirements specification and helps to avoid misunderstandings. The main problem with glossaries is that we create them once and update them only rarely. In consequence, the majority of glossaries are not particulary useful. In this article, Qualicen consultant Maximilian Junker shows how you can get more out of your glossary and keep it always up-to-date.

Why use glossaries?

When a project team creates an innovative product, it comes up with new ideas and new concepts – and new terms to describe them. Especially in the early phases many similar terms for the same things fly about. The terms’ meaning changes while the team discusses, writes first requirements, creates first product versions and retrieves feedback. As long as the team doesn’t decide on a common language, discussing the ideas can get difficult and documents are easily misundertood. A glossary helps to agree on a common language and provides a starting point for new team members to get up to speed.

I recently reviewed a requirements specification in the railway domain. The topic was an extremely complex railway controlling system and I knew nothing about railway systems. The specification made heavy use of various acronyms which I had never read before. Luckily, the team carefully developed an extensive glossary explaining the domain terms and their acronyms in detail, allowing me to make sense of the specification.

Many glossaries are in zombie mode

Although a glossary can be the Rosetta Stone for understanding a requirements specification, most glossaries we come across are in “zombie mode”: Most of the key terms and acronyms of the specification are not listed. Instead, the glossary contains generic terms, for example, “software prototype”, which are not even used in the specification.

How do glossaries enter the zombie mode? Maintaining a glossary takes discipline and a small amount of work: The team must add new terms and acronyms used in the specification to the glossary, together with a description and possibly abbreviations for the term. Better still: The team adds new terms on a candidate list and decides together if and how they are added to the glossary. This helps to avoid conflicting or redundant glossary entries. Without proper tool support, maintaining the glossary involves manual work. Let’s face it: This is often avoided in the face of time pressure. As soon as undefined terms start to crawl into the specification they are hard to identify. Slowly, the usefulness of the glossary starts to fade and the glossary enters into enters the zombie mode.

How to avoid zombie glossaries?

A team can avoid zombie glossaries by making it an important deliverable, equal to the specification itself. Integrating it into the specifciation documents can help to stress its importance. Appointing a team member as a “terminology officer”, who is in charge of the glossary quality and performs reviews once in a while will go a long way, too.
Finally, introducing proper tool support for the glossary is very effective. For example, requirements tools, such as Doors Next Generation have built-in glossary features. Read here  a 2012 artice by David Moul, then DNG team member, on his experience with glossaries and DNG. The open source requirements authoring tools AutoFocus3 also has a nice glossary feature.

But in addition to constructive tools, analytics help, too. Our analysis tool Qualicen Scout also has a glossary analysis. It helps you identify acronyms not in your glossary or find discouraged terms. Let’s look at this analysis in a bit more detail. It is easy to set up, simply copy your glossary as a list of terms into the configuration field of the glossary analysis, on line per term.

If scout finds an acronym (you can also configure what to look for exactly) not in the list or one of the discouraged terms it will raise a warning. In the example below, the acronyms RCS and CDO have not been defined in the glossary, hence Scout issues a warning.

To sum it up: Glossaries help you to find a common language in the beginnging of a project and they are a helpful tool for new team members. However, to avoid glossaries becoming useless zombies you need to actively manage and maintain them. Using the right tools helps you here. Many requirements management tools have built-in glossary features. Use them! Additionally, using a requirements analytics tool like Scout continously helps to to identify undefined terms  and avoid zombie glossaries.