Blogs about Jazz

Blogs > Jazz Team Blog >

Only 5% are requirements

Over the past year or so, of the 4000+ artifacts created in the IBM Rational Requirements Composer product team’s own RRC Jazz repository, only 5% are textual artifacts of type “requirement.” We believe this dynamic is not unique to our team, and it points to important ways that teams can improve their chances of delivering what their organizations really need – and more productively.

Good requirements are the distillation of many conversations and explorations. Often supplemental information is needed to make sense of requirements and put them in context. This information can include process and use case diagrams, user scenarios expressed in UI sketches or wireframes. Some teams are finding they can reduce the amount of textual requirements by expressing requirements in various diagrams and sketches. Also many detailed requirements can be fleshed out as part of user experience (UX) design.

About the Requirements Composer team

The IBM Rational Requirements Composer product team is spread across North America, and parts of Europe and uses the following tools to develop IBM Rational Requirements Composer:

  • IBM Rational Requirements Composer (RRC)
    – Requirements definition and refinement
  • IBM Rational Team Concert (RTC)
    – Collaborative development
  • IBM Rational Quality Manager (RQM)
    – Test management system: test planning, construction, and execution
  • IBM Rational Performance Tester (RPT)
    – Performance testing tool used to identify the presence and cause of system performance bottlenecks

What has been interesting is that, over the past year or so, the vast majority of the 4000+ artifacts that have been created in the RRC Jazz repository have been artifacts other than textual requirements.

Artifacts by Type

If we examine the artifacts by type (and RRC supports more types than those listed), we find that those high-level requirements that are “traced” through the development lifecycle and appear in RTC Release Plans, and RQM Test plans, they account for only 5% of the created artifacts.

The rest of the artifacts are the supporting collateral, including user interface sketches, storyboards, use cases, design, service specifications, customer feedback etc. The product team has been using RRC as a super wiki married to a collaborative requirements tool.

Artifacts created by project role

If we examine the data further we also find that the “Analyst” role, represented in the below chart by the “Stakeholder” and “Product Manager” role is a relatively small contribution of the artifacts, to the product development.

It is also interesting to note that people in nearly all the roles created artifacts of many types, with the User Experience (UX) team creating mostly visual artifact types, and in particular lots of images. RRC makes it easy to reuse / inherit User Interface (UI) elements as you create UI mock-ups and propagate changes immediately and accurately. Much of Version 2 of RRC is about changes to the existing rich client, and the creation of a new web client.

One of the 5% of defined requirements

Let’s examine one of those requirements in detail, the Review and Approval feature under development for RRC V2.

We started off with a simple, high-priority requirement, and then iteratively expanded upon this idea, adding increasing detail as we grew in our understanding about what was really needed. As part of doing this we created the following additional artifacts to facilitate our conversations and document what we were implementing:

  • Initial Sketch, which was a rough idea
  • High-level Scenario document, with supporting Business Process Diagram workflow
  • Use Cases (Create, View, Update, Edit Reviews)
  • Storyboards (for both the Web and Rich clients)
  • User Interface Specifications
  • Service Design
  • Development demos
  • And other supporting documentation

In Requirements Composer these are artifacts are related to each by hyperlinks, and comments and previous revisions are immediately at hand.

Some of the artifacts have been touched many times by numerous members of the team. For example the “Create Review” storyboard underwent 79 revisions and received 55 comments.

We enjoyed the following benefits of this wide-ranging collaboration:

  • Elicited more and better feedback before code is written (both requirements and feature design). This enabled the team to converge faster on the “right” requirements and reduced churn/rework that would have resulted otherwise.
  • Increased range and depth of stakeholder participation. Better information visibility enabled the team to identify gaps and clarify misunderstandings more quickly.
  • Allowed the RRC developers to communicate better amongst themselves, especially across component teams. This “lower cost, higher value communication” made the development team more productive.
  • Allowed people who joined the team later (for example: new developers and testers) to gain a deeper understanding of what we intended to build and why and do so quickly with less need to seek out the experts and interrupt them.
  • Made creation of test cases easier because testers did not need to seek out the developers but found most of the information in the RRC repository.
Robin Bater
Communities of Practice Architect
Executive IT Specialist