Tag Archives: requirements traceability

Requirements Traceability

The marketing or product management team have produced something called a “PRD”, or product requirements document, the contents of which they have promised to a customer. Meanwhile the development team have constructed a product backlog, which has been been captured in an agile management tool like Rally or JIRA. You look in the agile tool for the current iteration and you see all sorts of records: Epics, User Stories, Sub-Stories, Tasks…and you wonder: which of the customer requirements are we delivering in this iteration?

Thus begins the customer-developer communication gap. Depending on the complexity of the system or application being developed, the requirements may need multiple levels of decomposition to get down to the user story level of granularity. For example: “As the pilot of the space shuttle, I wish to dock with the international space station” is not a user story. It is certainly not something that could be delivered in a 2-week iteration. On the other hand, a story like: “activate the ready-to-hook sensors”, which may be an actual 1-iteration user story, but may resemble nothing like the parent-level requirement to dock the shuttle, and without seeing the hierarchy, there is no way to assess its contribution to the overall requirement.

In a large project we may end up with thousands of user stories. Furthermore, the development team may add many so-called ‘infrastructure stories’ that have no direct relevance to the customer, and frequently complicate the reporting of PRD-level progress. Assuming we do not want our backlog to be an unstructured list with thousands of items, we might organize it around a generic requirements hierarchy based on something like:

  • Themes: Chapter headings in the PRD
  • Epics: Feature Requirements (customer-facing statements of need)
  • Parent Stories: Technical Requirements (feature technical requirements and constraints)
  • User/Component Stories: Implementable in a single iteration

Fig. 1 Generic Requirements Hierarchy

I’m calling the layer below the epics ‘Parent Stories’ (we could also use terms like ‘System Stories’ or ‘Master Stories’). This is the level of detail one would typically see in a traditional Software Functional Specification (SFS). I’m calling them parent stories because it may take one or more levels of further decomposition to get to the level of granularity that is appropriate for an iteration. From a planning perspective, Epics => Parent Stories belongs within the realm of release planning, while Parent Stories => User Stories is carried out in iteration planning.

The first step in developing a backlog that is traceable to a PRD is to get the PRD-level requirements enumerated, meaning each requirement is assigned a unique identifier. To do this a requirements management tool could be used to auto-generate the identifiers, or a spreadsheet could be used. Eventually we will end up with a set of requirements that is structured something like:

The next step is to get the PRD into the agile management tool. Some tools (e.g. Rally) support multiple levels of hierarchical decomposition which makes it mush easier to visualize the structure of the requirements. Other tools (e.g. JIRA) have limitations on the depth of any hierarchy. In both cases however, we need to do some configuration work in order to achieve 2 fundamental goals in support of traceability:

  1. Unambiguous identification of PRD items
  2. The ability of search and filter for PRD items

To support the above we need to add a couple of things to our agile tool:

  1. Use the “tag” attribute to identify those items which are from the PRD
  2. Addition of a user-defined field (most tools support this) to store the PRD reference id

Having done this our tool, when loaded with a mixture of PRD and non-PRD items will display something like:

Finally, reporting progress against completion of the PRD becomes straightforward. Most tools have custom views which can be constructed using specific fields or tags. Some also have query builders allowing you to create a query like:

select * where project = “XYZ” and sprint = “Sprint-3″ and tag contains “PRD” and status = “Accepted”


Agile Requirements Management

There are several reasons why some companies want to have a disciplined requirements management process:

  • The organization needs to comply with regulatory or quality management system standards, like ISO9001 or TL9000, and is subject to regular audits to verify compliance.
  • The organization builds software to contract and needs traceability mechanisms to ensure that every requirement has been delivered and validated.
  • The organization develops large scale software, and while embracing the principle of “working software over documentation”, is not confident that post-it notes are a reliable way of managing thousands of requirements.

Thus the organization needs a way of defining user requirements, tracing them through the development process, and managing changes. Documentation is certainly not the goal, but can be a necessary part of the process to achieve the goal of guaranteeing the needs of customers and stakeholders have been met. Just as doing iterations is not the same as being agile, there is no contradiction in being ISO9001-compliant and operating a highly agile development process – continuous integration, unit test automation with coverage measurement, and highly automated system and regression testing.

The process/tools we use to deliver an effective requirements management process must meet 2 key goals:

  1. Demonstrate Traceability
    • At minimum demonstrate upstream traceability between the customer-facing product requirements (“PRD”), or the customer contract, and the internal Epics and User Stories that the development team is building.
    • Ideally also show down-stream traceability between user stories and test cases (and software bugs) so that test coverage and delivered quality of the requirements can be measured and quantified
  2. Provide Structure
    • With many of the commercial agile tools it is very difficult to see the forest from the trees. When I look at the user story backlog for a product in a tool, I would like to see something that resembles the PRD, not an unstructured list of items that leaves me wondering if we have captured everything in the contract.

In Fig. 1 below we have (in a spreadsheet) the contents page from the PRD/Contract, with user stories created for each feature. This layout provides both traceability and structure.

Figure 1. Requirements Traceability and Structure