Introduction

The goal of the glossary is to provide a common vocabulary on which all of the stakeholders agree. The glossary defines the meaning of all business terms relevant to the system being built. These serve as the foundation for all requirements models and business rules.

Key details of how to use the technique

Any project can create a glossary by capturing technical terms and jargon used on their project. Follow-on projects can add to the glossary.

Create the glossary early in the project and keep it up-to-date.

Define specialized terms from the application domain. Include synonyms, terms that can have multiple meanings, and terms that have both domain specific and everyday meanings

Don’t include a glossary in every document – this can lead to different definitions. Instead create a single glossary and point to it from other documents. If possible, use an enterprise-level glossary. Any deviation between the main glossary and a project’s use of a term can be captured in a project-specific glossary

If necessary, appoint a glossary guardian to make sure all key business terms are captured and they are used consistently

Situations in which the technique best applies

Create a glossary whenever there is a reasonable doubt that the terms used may have multiple meanings.

Strengths

The glossary can help reduce ambiguity—the source of many problems on a project. One of the key causes of ambiguity is using words that can be interpreted multiple ways and using multiple words to mean the same thing.

The glossary can also help you reach mutual understanding—among people from different functional groups or product lifecycles—of the big picture of the system.

A glossary that defines specialized terms from the application domain will reduce misunderstandings. It can also speed up communications since abstract terms can be clearly defined and consistently used.

Possible Gotchas

Ways to use it incorrectly

• Allowing individuals to maintain “power” by not defining terms
• Being overzealous: trying to define every term
• Having a term defined in multiple places, usually differently
• Making the glossary too difficult to maintain (e.g. excessive change control)

Situations in which it is a bad match

• When all the terms are clearly understood or are defined elsewhere.

Where to go for further information

Ellen Gottesdiener, Requirements by Collaboration, Addison Wesley, 2002. Planning and conducting workshops. In addition, Chapter 2 provides a good overview of Wiegers’ requirements process and a great discussion on which models are appropriate for different situations.

Scott Ambler, Agile Modeling: Effective Practices for eXtreme Programming and the Unified Process, John Wiley & Sons, 2002
Also: The Official Agile Modeling Site. http://www.agilemodeling.com/
An impressive set of links on modeling. Includes links to summary descriptions of a wide variety of modeling artifacts and essays on creating light-weight models and agile documentation.

Suzanne Robertson and James Robertson, Mastering the Requirements Process 2^nd Ed, Addison-Wesley, 2006

Requirements Boot Camp seminar

Use Cases in Depth seminar

CxOne, Construx’s software engineering framework.

Terms and Acronyms

This document defines terms and acronyms used in [project name]. Some terms are unique to [project name]; most are precise [project name] definitions for the [application domain] terms. Common dictionary, computer science, project management, and engineering terms employed by [project name] are not listed here unless a precise definition is critical for their use in [project name].

Cross-references to terms in this document are denoted by italicized text. References to other [company name] documents are by file name.