Dr. Dobb's is part of the Informa Tech Division of Informa PLC

This site is operated by a business or businesses owned by Informa PLC and all copyright resides with them. Informa PLC's registered office is 5 Howick Place, London SW1P 1WG. Registered in England and Wales. Number 8860726.

Channels ▼

Don't Enter the Matrix

SD's Agile Modeling Newsletter :: October 2005

Requirements traceability is the capacity to relate your requirements to one another and to aspects of other project artifacts. Its primary goal is to ensure that all of the requirements identified by your stakeholders have been met and validated. In my experience, traceability is a great idea in a small minority of situations, but for most project teams, it becomes a bureaucratic quagmire whose costs far outstrip its purported benefits.

Let's start with some definitions. Vertical traceability identifies the origin of items (for example, customer needs) and follows these items as they evolve through your project artifacts, typically from requirements to design, the source code that implements the design, and the tests that validate the requirements. Horizontal traceability identifies relationships among similar items, such as between requirements or within your architecture. This enables your team to anticipate potential problems, such as two subteams implementing the same requirement in two different components. Traceability is often maintained bidirectionally: You should be able to trace from your requirements to your tests and from your tests back to your requirements.

Organizations that take a formal approach to traceability often create a traceability matrix, which externally maintains metadata about tracing relationships between artifacts. As you can imagine, maintaining a traceability matrix is a lot of work; I've been on traditional teams in which one or more people have been assigned to this task alone, often using tools such as IBM's Rational Requisite Pro, Borland's CaliberRM or Telelogic's DOORS/ERS. These teams need one or more designated people for this work—a meager staff has little chance of keeping it up-to-date. An out-of-date matrix is worse than having no matrix at all because it contains erroneous information upon which invalid decisions will be based.

Agile developers realize that traceability is important, but we don't waste our time creating extraneous matrices unless our stakeholders insist on it (more on this later). Instead, we use tools and techniques that allow us to maintain traceability without the burden of a traceability matrix. For example, when we capture a requirement in our product backlog, we assign it a unique number. This number is then referenced by our tests and source code as necessary. Better yet, we single-source information and simply treat acceptance tests as requirements in their own right, reducing our overall traceability needs because we capture the information only once. We then reference the requirement ID in our source code comments—for example, via a JavaDoc tag in Java—implementing the traceability back to the source requirement. If we're using a modeling tool to do our architecture and design, we expect it to implement traceability features automatically. For example, if you use a modeling tool that generates and reverse-generates code, suddenly you have traceability from your models to your code, which in turn traces back to your tests and requirements via the embedded references.

Another challenge, at least in traditional organizations, is the tendency to update artifacts in a misguided attempt to keep everything in sync. The problem arises whenever a requirement changes—and they always do: You must update everything possibly affected by the change. The good news? Your traceability matrix helps to identify what may be affected by a change. The bad news? You're motivated to make the updates even if you don't really need to. When you can "easily" follow a change through your morass of documentation, the bureaucrats will insist that you make what they feel to be appropriate updates. I guess this makes sense—if you have all the time in the world and an endless budget.

Agile software developers instead follow Agile Modeling's "Update Only When It Hurts" practice, updating an artifact only when necessary, not simply because they can. In fact, few systems have perfect documentation, yet we manage to keep them in production for years. Our job is to build working software, not to write documentation that will likely be ignored by the people responsible for maintaining the system. Don't get me wrong—we do write documentation, but we write it in an agile manner.

Traditionalists argue that traceability matrices make it easier to gauge the impact of a changed requirement because they enable you to easily identify the aspects of your system that may be affected by the change. However, estimation experts will tell you that the most effective estimates are done by the people who know the system, and better yet, are responsible for implementing the change. What's easier and less expensive to estimate the impact of a change—having one or more people on a change control board (CCB) work through a traceability matrix or simply asking someone who knows what he's talking about?

Why are so many people interested in requirements traceability and, in particular, traceability matrices? First, process frameworks such as the Capability Maturity Model Integrated (CMMI) mandate the creation and maintenance of traceability metadata on projects. Specifically, practice 1.4 of the Requirements Management (REQM) process area states, "Maintain bidirectional traceability among the requirements and the project plans and work products." This practice is often interpreted by traditionalists as a requirement to create a traceability matrix, but you could easily adopt the agile techniques I've described here instead. Second, overly specialized IT professionals often can't understand each other's work products. How many times have you heard somebody claim "If the documentation is in the code, the information is lost"? The information is lost only to anyone who can't read code. Overspecialization makes us write far too much documentation to capture the same information in several places—so maintaining a trace among all this stuff starts to make sense. Third, traceability tool vendors are fairly persuasive. Managers often buy their wares whether they're needed or not, and force development teams to use them to justify the purchase.

The fourth lure of the traceability matrix is its support of auditing efforts. Sometimes this proves reasonable—sometimes, but not always. For example, many teams must comply with the Food and Drug Administration (FDA) or Sarbanes-Oxley (SOX) regulations. If you have an actual business need to support auditing—not just an internal bureaucratic requirement to cater to your audit group—clearly you need to do so. However, just because you have clear compliance requirements to maintain traceability, you needn't be stupid about it—do just enough work to comply with your audit needs, and no more. Don't use a full-blown requirements traceability tool when a spreadsheet would do. And don't create a spreadsheet when unique IDs and embedded references to those IDs would do.

The costs to maintain traceability matrices, even if you have specific tools to do so, almost always outweigh the benefits. Agile developers make their project stakeholders aware of the real costs and benefits and let them decide whether or not to invest in that work. A traceability matrix is effectively a document, and in the agile world, that makes its creation a business decision. Remember that traceability is the true goal, not the creation of a traceability matrix. Keep it simple, keep it simple and keep it simple.


* * *

I'd like to thank Craig Larman for his insights into agile approaches to traceability. In late September, he was kind enough to provide feedback regarding the Agile UP product, and a good portion of it focused on traceability. Find Agile UP at http://www.ambysoft.com/unifiedprocess/agileUP.html

Agile Estimating and Planning
Mike Cohn, author of User Stories Applied: For Agile Software Development (Addison-Wesley, 2004), has done it again. As the title suggests, he offers practical advice for taking an agile approach to estimating and planning—advice applicable to both agile and traditional teams. The Project Management Institute (PMI) could learn a thing or two from Mike. To be released later this month, "Agile Estimating and Planning" argues for fundamental concepts such as keeping the estimates for cost and schedule separate, the importance of planning, building the best possible product given the resources at hand, effective scheduling, and then monitoring the project and adjusting your estimates and plans based on what you've learned. Sounds like basic stuff? You bet it is, but in my experience, few project teams—even those with PMI-certified managers—seem to estimate and plan their efforts effectively. If you want to succeed at adopting agile approaches in your organization, or if you just want to improve your project management skills, this book is for you.

Agile Estimating and Planning
By Mike Cohn
Prentice Hall PTR, 2005


For tips on agile project management, visit

An agile approach to requirements elicitation and documentation is described at

Agile requirements best practices are covered in the article posted at

Agile documentation techniques which reduce your documentation burden, and thereby reduce the need for traceability, are described in detail at

The Sarbanes-Oxley (SOX) act is summarized at

The CMMI approach to requirements traceability is overviewed at

The Agile UP product can be downloaded from

The agile practice Single Source Information is described in detail at

The Agile Alliance homepage is the best starting point for anyone interested in learning more about agile software development.

The Agile Models Distilled page provides links to overviews of a wide variety of models at

The principles of Agile Modeling v2 are described at

The practices of Agile Modeling v2 are described at

Check out the Agile Modeling mailing list at

Get agile modeling training resources at

Related Reading

More Insights

Currently we allow the following HTML tags in comments:

Single tags

These tags can be used alone and don't need an ending tag.

<br> Defines a single line break

<hr> Defines a horizontal line

Matching tags

These require an ending tag - e.g. <i>italic text</i>

<a> Defines an anchor

<b> Defines bold text

<big> Defines big text

<blockquote> Defines a long quotation

<caption> Defines a table caption

<cite> Defines a citation

<code> Defines computer code text

<em> Defines emphasized text

<fieldset> Defines a border around elements in a form

<h1> This is heading 1

<h2> This is heading 2

<h3> This is heading 3

<h4> This is heading 4

<h5> This is heading 5

<h6> This is heading 6

<i> Defines italic text

<p> Defines a paragraph

<pre> Defines preformatted text

<q> Defines a short quotation

<samp> Defines sample computer code text

<small> Defines small text

<span> Defines a section in a document

<s> Defines strikethrough text

<strike> Defines strikethrough text

<strong> Defines strong text

<sub> Defines subscripted text

<sup> Defines superscripted text

<u> Defines underlined text

Dr. Dobb's encourages readers to engage in spirited, healthy debate, including taking us to task. However, Dr. Dobb's moderates all comments posted to our site, and reserves the right to modify or remove any content that it determines to be derogatory, offensive, inflammatory, vulgar, irrelevant/off-topic, racist or obvious marketing or spam. Dr. Dobb's further reserves the right to disable the profile of any commenter participating in said activities.

Disqus Tips To upload an avatar photo, first complete your Disqus profile. | View the list of supported HTML tags you can use to style comments. | Please read our commenting policy.