Managing Requirements — One Approach That Works

October 3, 2010

I’ve had some recent conversations with colleagues and clients about “managing requirements”.  I was surprised at some of the approaches that had been tried — largely unsuccessfully.

And while I don’t claim to have THE answer on this subject, this approach has one significant advantage — it has worked in the past.

Some Background

I believe that “requirements” consist of many different things, including:

  • Issues reported by customers that highlight a need for better capabilities
  • Problems discovered by internal resources that highlight product gaps
  • Market opportunities that identify broad functional capabilities that could be targeted
  • Customer / prospect discussions that contribute specific product needs.  Often this includes “gaps”.
  • Enhancement requests that explain (sometimes in great detail) specific functions where the product needs to be improved

Thus, there is a wide range of specific and broad “requirements” provided by all sorts of internal and external people — and many of the requirements need to be grouped together — either because they logically go together or because without enough critical mass, none of the smaller items could justify the effort to address them.

Lastly, requirements change over time — either because your understanding of what is needed evolves or because the need itself changes.   (For example, if  a requirement specified that your software should support a dual-core processor and a quad-core processor was introduced before the requirement was addressed — you would probably want to update the requirement.)

Required Tools

I believe strongly in using tools for the function they were designed for.  So, I don’t use a hammer to “drive in” a screw — that’s what a screw driver is for.

Thus, I believe that you need the following tools to manage your requirements:

  • Issue Tracker — a tool for collecting, prioritizing, scheduling, and tracking all sorts of issues, including many of the requirement types discussed previously.  My favorite is JIRA, but there are many others just as good.
  • Document Management System — a tool for collecting, tracking, sharing, and managing all sorts of documents.   My favorite is Alfresco, but there are many others.

You may wonder — Why a Document Management System?   Because some requirements require more than a few paragraphs to adequately describe and as previously discussed — requirements may change.  If these “larger requirements” are captured in one or more documents and linked to the issue within the Issue Tracker — you can update the requirements whenever it is necessary without having to update the issue within the Issue Tracker.

My Approach

Here’s the “short” or “cookbook” version…

System Setup

1.  Create issue types (in the Issue Tracker) for the types of information you need to track.  This could include:

  • Bugs
  • Enhancements
  • Product Improvements
  • Major Features
  • Use Cases
  • Stories (and Epics)  — If you’re using Agile.

2.  Add fields to each issue type so that you can capture planning information.  For example:

  • Dev Estimate — how long it would take to implement this issue (or requirement)
  • Dev Estimate Assumptions — any assumptions that were used to estimate the level of effort.  (This is critical unless you plan to re-estimate each task just before you do it, because situations and people change — and you won’t be able to remember the details of each estimate unless the person who made the estimate keeps notes.  And if they are going to keep notes, why not put them in the system?)
  • Dev Estimate Confidence — how confident is the Development organization in this estimate?  “High, Medium, and Low” are often enough, but you may wish to use a percentage.
  • Reference Doc — a field where you put the link to the reference document (within your Document Management System).   You can also create a separate issue type of “Reference Document” so that you can link multiple documents in your Document Management System to the issue — if you commonly need to refer to multiple documents.

3.  Add “planning” capabilities to your Issue Tracker

You need a method to plan which issues (or “requirements”) will be developed next.  If you are using JIRA and Agile, you could use the GreenHopper planning plug-in.  Or you could add a “Target Release” field and pre-populate it with the names of your next 3-4 release vehicles.

The specific tool is unimportant — as long as it is easy enough for you to use, so that you can (and will) use it regularly.

Using the System

1.  Create documents for anything that can’t be described in a couple of short paragraphs or when the description might change over time.

Use your Document Management System to circulate the documents to appropriate internal (and external) stakeholders — so that each requirement is described appropriately.  You don’t want to waste Development time on poorly defined requirements — so spend the time to get them right.

2.  Create issues for each requirement and establish links to their respective documents.

3.  Create higher level “Major Feature” issues

Group related smaller enhancements and improvements under each Major Feature.  JIRA makes this easy with Links.   Other systems offer similar capabilities.

4.  Create individual issues for each customer request

Each time a customer requests a given feature or enhancement, you should record it as an enhancement issue.  And link each customer enhancement issue to an appropriate Major Feature issue.  Thus, when you are evaluating which features to do — you will have a record of the number of customers who requested something, who they are, when they requested it, etc. — which is incredibly valuable.  Imagine your credibility when you contact your favorite customer to ask them if they would like to test a new feature that they specifically requested… (Of course, they will be happier if you are providing their feature sooner than later — but that’s a different issue.)

5.  Plan each release

Plan each release based upon the content that you want to include, the amount of customer interest, and the roll-up of the estimated development effort.

And since YOU decide how frequently you want to launch new releases, you can use this approach for Agile sprints (3-4 weeks) or for major multi-year waterfall releases.


In summary, all requirements (or issues) get recorded in the Issue Tracker system.  All documents belong in the document management system (such as Alfresco).  Documents are written using standard tools (Word, Excel, Powerpoint, etc).  The Issue Tracker becomes your planning tool and you use the workflow and revision control tools of your document management system to manage the distribution, review, revising, and approval of all relevant documents.

I won’t pretend that this is a perfect system — but it DOES work.  And since these types of tools are already being used within a given company — it is MUCH easier to share information with others in the company and to capture data that already exists. Otherwise, you have to convince people to use “yet another system” and duplicate data between your bug tracking and requirements management system — which is simply too much work, invites multiple (and different) definitions of each issue, and makes it far too easy for things to fall through the cracks.

Next time I’ll discuss the benefits of using a Document Management System (such as Alfresco), instead of a source code control system (such as Subversion), to manage documents.

Thanks for reading this far and now it’s your turn…   How do you manage requirements?  How well (or poorly) does your system work?   Is there anything about my approach that needs improvement or concerns you?

Let’s hear what you think…



%d bloggers like this: