Glossary of Terms

When I was first introduced to the notion of a glossary as a requirements analyst, it was explained to me at a very superficial level. To paraphrase – the glossary holds the definitions of the terms that people on the project might not understand. The intent was simply to provide a dictionary function – a place to look up the domain-specific and esoteric terms that developers or testers would find in the requirements. An easy way for people to know what the requirement is talking about.

A glossary of terms is much more than that.

A glossary of terms is a tool that provides the following benefits:

• Explicitly defines the nouns that are referenced in the requirements.
• Eliminates one of the many sources of ambiguity in the requirements.
• Is the foundation for other key requirements artifacts, especially a fact model.*

*A fact model will be the subject of one or more future articles, but for now, think of it as a model that defines the language used to express the relationships between business objects (nouns), as they are defined in the requirements.

It is worth noting that the glossary of terms and the fact model are critical to writing unambiguous rules – and after reading this article, if you aren’t convinced that they are critical to writing unambiguous requirements, then comment below.

Unenlightened Definitions

After attending the 10th International Business Rules Forum last week, I felt like I had been hit over the head with the “well, duh!” club. I knew what a glossary was, and how and why to use it. I never thought it was a big deal – so I never wrote about it. Now I know what I already should have appreciated about how important a glossary is to writing good requirements. I wrote the heading for this section, anticipating a review of some of my favorite requirements books – to see how they deal with glossaries. The treatments must not have been as insightful, or how could I have been so unappreciative for so long?

1. Managing Software Requirements, Second Edition. There is no mention at all of having a glossary of terms in this otherwise good book. And they even have an entire chapter dedicated to removing ambiguity from requirements!
2. Requirements by Collaboration. The best book on JAD sessions. This book has a good definition – “These terms serve as the foundation for all requirements models and business rules; the goal of the glossary is to provide a common vocabulary on which all of the stakeholders can agree.” However, this introduction has only two short paragraphs explaining what a glossary of terms is – not addressing how important it is. There is a good idea for running requirements sessions – to assign a glossary guardian during a session to record any business terms that crop up during the session.
3. More About Software Requirements. No mention.
4. Patterns for Effective Use Cases. No mention.
5. Writing Effective Use Cases. No mention.
6. Software Requirements, 2nd Edition. Ends a sentence in a paragraph on unambiguous requirements with “Define all specialized terms and terms that might confuse readers in a glossary.”

OK, enough bashing of my favorite books on requirements management (and they are my favorites). The point is, the glossary of terms is getting short shrift in the larger requirements community. Where other larger and smaller ideas get entire books, the glossary of terms hardly gets mentioned. If your favorite book isn’t on this list, chime in and let us know how it treats glossaries.

Glossary Gets Its Due

Business Rules Concepts, by Ron Ross, however, puts more emphasis on the glossary of terms. Ron starts by making a point of specifically defining the glossary as a glossary of terms – and provides this definition of “term” (via Merriam-Webster’s Unabridged Dictionary, 2000):

Term: a word or expression that has a precisely limited meaning in some uses or is peculiar to a science, art, profession, trade, or or special subject.

Ron goes on to spend a few pages emphasizing the importance of the glossary of terms, both on its own, and as the foundation for other artifacts that are critical to managing business rules. As we’ll see in future articles, some of these techniques will prove invaluable in managing requirements too.

Glossary of Terms

A glossary of terms, using the definition of term that Ron provides, is simply put, a list of all of the terms that represent specific nouns in the domain in which we are writing rules (or requirements). These are the subjects and objects of rules and requirements. They expressly represent relevant business concepts. Terms, by Ron’s definition, are always nouns. We’ll stick with that.

Every business term, however apparently obvious, should be considered. In two separate sessions at the IBRF conference by Ron and an employee of Ron’s company, Kristen Seer, Business Rule Solutions, we were exposed to some “obvious” terms that proved to be ambiguous. Here are a couple, plus some of our own.

• In baseball, what is the definition of “ball“? Is it a non-strike? A round object hurled by a pitcher? The game itself (“Play Ball!”)? Ron is famous for his baseball-rules examples.
• For an electric utility company, what is “load“? Is it the total power demand of all devices on the network? Is it the power demand of a single device on the network? Is it the minimum or average power demand over a period of time?
• Is a “customer” someone who might purchase products from us (e.g. someone to whom we market)? Or is a customer someone who has purchased in the past? Or is in the process of purchasing?
• Is “profit” measured net or gross? Is margin a dollar amount or a percentage? Contribution or total?
• Is “enrollment” what a student does for a class, or the count of all enrolled students?

The point is this:

Glossaries should include not only the esoteric terms, but especially should include the common and obvious terms that are subject to interpretation.

Imagine exploring the centralization (or possibly federation) of existing global, decentralized processes. Among other things, you are looking at the processing of sales transactions. And you are dealing with shopping carts, quotes, orders, and purchase orders. These different terms mean different things to different people – even within a single geography. And they evoke not only passionate opinions, but the interpretations (and misinterpretations) of these terms may have very sweeping impact on some high level decision making – beyond what they reasonably should. Do you want a glossary of terms now?

These terms, when undefined, introduce ambiguity into your requirements. You need to define them, and gain a consensus on the definitions. And you should reference all of the artifacts (use cases, requirements, etc) that use the terms (or reference all of the terms used in an artifact).

You can maintain a glossary of terms within your repository, in an excel file, a wiki, a word doc, or even a sharepoint list. The way your team interacts with these terms will dictate which mechanism is best. If you are managing requirements (or rules) in a repository, then a repository will probably be the best place to maintain the list – as it should simplify (or automate) the traceability between artifacts that reference the terms and the terms themselves.

Conclusion

The guidance we generally hear, to include terms that “might confuse someone” is right. It is also under-emphasized. Who would expect “customer” and “quote” and “margin” to confuse someone? If two people assume different definitions for those terms when reading your requirements, then at least one of them will be confused.

Don’t underestimate the potential benefits of maintaining a glossary of terms as a key component of your requirements development. Future articles here will present ideas that leverage the glossary of terms, and existing artifacts will get benefits immediately from the reduction in ambiguity.

We had a great interview with James Taylor a couple weeks ago, where we talked about his new book, Smart (Enough) Systems, co-authored with Neil Raden.

James is an expert on decision management systems. I spent the late 1990s working on “rules-centric” software systems that allowed us to isolate rules and manage them seperately from other software requirements.

Traditional structured requirements approaches focus on the gathering and management of software requirements, but they gloss over the gathering and management of business rules.

James and I are exploring the best ways to bring these two points of view together.

As part of this study, one of the first things we can do is describe the areas of overlap, or rather, how the two worlds (business rules and requirements) interact. From a requirements-centric perspective, one place business rules live is within the decisions that we discover when gathering requirements.

Decisions

Use cases and process flows involve decisions. In use cases, these are often represented as alternate flows and exceptions. In process flows, they are represented with the familiar diamond shaped box. Conceptually, there are one or more rules that combine to make a decision. And in requirements documents, you often see convoluted language, well-organized tables, or other representations of those rules.

These documents embed the rules within the requirements. And that leads to the rules being validated, verified, implemented, and tested within the greater context of the requirements.

Another example of decisions can be seen easily when using UML statecharts. These decisions are somewhat implicit – as they are defined as the criteria for, or ability to change the state of business objects. In other words, the conditions that allow change are in effect decisions. While it may be harder to find them, these decisions can also be found in use cases. But there are good arguments for using both use cases and UML statecharts together.

What’s The Problem?

As James points out in his new book, one of the worst things you can do is embed the implementation of business rules within a software application. So there’s a fundamental flaw in embedding business rules within requirements.

Requirements management approaches tend to either embed business rules within other artifacts. At the same time, rules-management systems are optimized for the management of rules, with little focus on requirements. Each approach is designed to solve a single problem, and neither sufficiently addresses the challenge of getting the best of both worlds.

Moving Forward

James and I will be exploring the issue of how best to bring these two worlds together over the next few months.