Requirements Management – I’m embarking on a journey to help several teams manage their requirements with their existing systems and tools.  This is the first in a series of articles, where the rubber meets the road.  I’ll look at both the theory and the realities of what works (and doesn’t) in practice.  I hope you’ll come along for the ride.

The Idea That Makes it Tricky To Manage Requirements

OK, so I’m working with a product management team that is working with multiple software development teams.  The development teams already have tools and systems in place for tracking work within projects.  The development teams are mostly using Atlassian’s JIRA for tracking activity.  The teams also have Atlassian’s Confluence wiki for capturing “other stuff.”

The development team has a good working process for managing their delivery activities within the “JIRA world.”  From the top down view, you find a project (in JIRA) that represents what will be delivered in a particular release.  Within that project, you see the issues (or user stories or requirements) and associated tasks that were previously scheduled for that release.

This is pretty effective for getting a handle on what’s happening.  Where it falls short is in getting a comprehensive understanding of why it is happening.  And that’s the view product managers need.

Why something needs to happen is completely different from when something needs to happen.  That’s what makes this tricky.  Consider the following analogy.

You’re driving across the country from Los Angeles (LA) to Manhattan (NYC).  Your goal is to get to Manhattan.  Your product manager creates a map, breaking down, roughly, how you will get from LA to NYC.  Your product manager is riding shotgun in the car, and he’s responsible for telling the driver where to go.  Your developer is driving the car, and is responsible for getting the car wherever the product manager tells him.  They share the responsibility for getting to NYC – neither of them can do it alone.

They climb in the car, and start driving.  When the developer has a question about a particular way to go (which highway to take, etc), they communicate.  Together, they make great progress.  After a while, the gas tank is empty, and they stop to fill up.  This is a logical break in the drive, and they stretch their legs, get some dinner, whatever.  With a full tank of gas, they get back in the car and start driving again.

Managing requirements inside the context of a release (in JIRA) is like saying every time you stop for gas (finish a release), you should create a new map.  The goal (destination) is independent of the release cycles (gas tanks).  The requirements should live outside the release.  However, the turn-by-turn information is useful inside the release.  The product manager needs to provide the next level of detail (first, get to Las Vegas, then stay at the Westin,…) for each “tank of gas” – after which, that information is not very valuable, and can be discarded.  But the goal (reach NYC) stays alive.

A process and system for managing requirements should not force product managers to recreate documentation for each release.  Your stakeholder (perhaps you’re delivering a donated kidney to a hospital) needs to know when you’re going to deliver the kidney.  The last place they should have to look for that information is within the context of the current project.

This is what makes it tricky.

JIRA and Confluence

This is not a series of articles around picking the best requirements management solution available today.  These articles will cover the exploration of using JIRA and Confluence to make (1) the product management teams more effective, and (2) the combined product delivery teams (management, marketing, development, quality) more effective.  We’re faced with a real-world constraint that we will use these tools that are already in place.

Product Management Goals

There are a series of goals that we have, that will inspire our implementation choices (of how we use Confluence and JIRA), and ultimately provide the measure of our success.

• We will not remove or regress things that are working today.  The implementation teams (development and test) are delivering products, and using JIRA to track issues and tasks.  Whatever we do must not break this current world.
• As product managers, we are continually investing in, and updating, our understanding of our markets.  We need a solution that allows us to record that information in a way that we can (a) share with each other effectively, (b) remember what we need to remember, (c) make changes as needed so that the view we have documented is always reflected of the understanding we have “in our heads.”
• As a delivery team, we need to connect the two worlds (“what am I doing” and “why are you doing it”), so that the product managers can let the implementation team know what to do next (and what they will eventually be working on).
• As a company, we need to set and manage expectations – internally to stakeholders and externally to customers and partners.

These are the problems we’ll be tackling.

This series of articles will capture elements of implementation choices, why we made them, and the rationale “behind the whys.”

I hope you’ll come along for the ride.

Some books on how to write and manage requirements mention using a glossary. Most books on requirements don’t go into enough detail about either the importance of a glossary of terms, or the precise use of the glossary of terms. Or if they do, they under-emphasize the benefits of a well-defined glossary of terms. Walking a day in the moccasins of a business rules analyst helps us all appreciate the importance of a well-managed glossary of terms.

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.