Glossaries: An Agile Introduction

A glossary is a collection of definitions of terms. Every company has its own specialized jargon, and you need to understand it if you want to communicate effectively with the experts with which you working.You may want to include both technical and business terms in your glossary. Although you may understand what terms such as XP, C#, J2EE, and application server all mean your stakeholders likely don’t. Similarly your stakeholders may understand what business terms such as convocation, grant, and transcript mean but some developers may not. A glossary which includes both the relevant technical and business terminology goes a long way to improving the communications between developers and users – if you do not understand each other’s language you cannot communicate effectively.

Your organization may already have an existing glossary in place if so then reuse appropriate terms from it. Often your industry will already have a specialized dictionary describing common terms which you may want to adopt as well.

The best advice that I can give about creating a glossary is to be realistic. You’re not Webster’s – you don’t have to get the definitions perfect, they just need to be good enough. Furthermore, dictionaries have multiple definitions for most words so don’t be afraid to do the same. Ideally you want a single definition; realistically it often isn’t worth the effort to argue it out if it’s even possible to come to agreement.

An important issue with glossaries, with all artifacts for that matter, is to make them available to people. This is one of the reasons why AM includes the Display Models Publicly practice. You might want to consider documenting your glossary as a single HTML page that everyone can access and hopefully edit (remember the practice of Collective Ownership). Another option, particularly if editing a major concern, is to use a Wiki.

Remember that your conceptual/domain model, if you have one, will also refer to critical domain concepts. You should strive to single source information and capture a definition in the most appropriate place possible. I suspect that will be your glossary, not the domain model.

 

Source

This artifact description is excerpted from Chapter 7 of The Object Primer 3rd Edition: Agile Model Driven Development with UML 2.

Translations