Neuma Technology: CM+ Enterprise Software Configuration Management for Application Lifecycle Management

Neuma Technology Inc. provides the world's most advanced solution to manage the automation of the software development lifecycle.
Neuma Technology Inc.

More white papers:

Find out more ...


Neuma White Paper:

Requirements Driven Development: A Stream-Based WBS Approach

Requirements. Must have. Should have. Want. OK, maybe not really requirements. But when it comes down to it, you need to understand why you're building what you're building in sufficient detail that you'll know if what you built does the job. And you need full traceability to show that you meet the requirements. Developers work to a set of requirements, but these are not the same as the product requirements, which are again different from the customers' requirements. And what about ad hoc requests? Where do they fit in?

The driver for requirements typically falls into one of two categories: a specific contract/customer or a general marketing strategy. One of these things is going to drive your requirements. If you have a $1B NASA contract, you'll be focused on that, largely to the exclusion of any other product requirements. If you're trying to capture market share, you be focused on both innovative and me-too features. If you've got a new high-priced product, you're likely going to focus on one or two contracts to get credibility before addressing the issue of market share.

Customer Requirements vs. Product Requirements

So we have: Customer Requirements and Product Requirements. Sometimes we build something specifically for a customer and the two are the same - the CRD (Customer Requirements Document) becomes the PRD. The PRD, is an important document for the development team - it describes what it being built. If there is one or more CRD, traceability from the PRD back to the CRD is essential. The Customer must still be able to verify that all the requirements in the CRD have been met.

Before going any further, there are a couple of other things to keep in mind. First, some PRDs describe the first "release" of the product, with subsequent release PRDs to follow. In other cases, the PRD describes the product and the product team may address it across a series of development streams, each culminating in a significant release.

Second, the PRD is not the sole source of input to product definition. Change Requests (CRs) tend to filter in as well. CRs are typically customer centric. The customer request usually arises from having used the product (or a prototype of it).

2D Version Control of Requirements

Your Requirements Management Tool should provide adequate facilities to manage your Customer Requirements Tree. Each element of the tree should be under both version control and change control. The tree itself may be baselined and frozen often. It should support 2-dimensional version control, with release streams forming one dimension, and within each stream, revisions. So the requirements tree can evolve within each release stream and can also evolve across release streams. This allows us to compare baselines across streams for identifying new release requirements, as well as within a stream, for identifying changes to the requirements and "requirements creep" within a release cycle.

Parallel Phase Requirement Trees vs. Work Breakdown Structure of Activities

There are two camps on how to proceed from here. One recommends a parallel requirements tree, a Product Requirements Tree, managed in the same way as the Customer Requirements. Then the Product Requirements may spawn a third similar tree, a System (or Software) Requirements Tree.

I recommend taking the second approach and using a WBS for your Product Requirements. More specifically, a WBS (Work Breakdown Structure) is generated for the release stream and the Product Features which flow out of the Customer Requirements baseline populate the WBS. The Customer Requirements Tree is really a mechanism for negotiating with the Customer. With the Product Requirements, you really want to do a lot more. You're negotiating with your Product Manager, but you're also building the specification, identifying and assigning resources, establishing and refining your effort estimates, prioritizing implementation and identifying dependencies.

The product manager wants to take the customer requirements (i.e. specific customer requirements, market demands, customer requests - including internally generated ones) and propose a feature and functionality content for the product. The WBS tree will start out as a feature set and should grow into a full product requirements functional specification. The WBS should then continue to grow, based on this specification, to identify all of the activities that need to be performed to bring this specification to an end product.

We want to track project activities of various types: Requirements Specifications (RS) , Design (and Implementation) activities, Documentation activities, Testing activities, Configuration Management activities, Project Management activities, etc. Just as the RS activities start out as a bunch of Product Requirements which later evolve into specifications, similarly, Design and Implementation activities start out as a set of System (or Software) Requirements. This happens after careful analysis of the set of specifications drawn up in the previous phase. These Design activities grow into the design specifications ideally attached directly to the Design activities, and clearly traceable to the RS activities. The Design activities are a different type of activity, but still very much a part of the same WBS. The goal of the WBS is to transform the product from ground zero to the first release or from one release to the next.

The Product Manager Role

We want to address the entire product, but at the same time, we want to start by focusing on the first release. How do we do this? Here's what I would do if I were product manager:

  • Identify the product requirements as line items - we'll call them RS Activities.
  • Identify the key objectives/deliverables for each of the activities, and split/merge requirements if necessary.
  • Prioritize each of the activities (e.g. high/medium/low or must/should/could)
  • Do a rough (e.g. High/Medium/Low) budget (i.e. cost or effort sizing) for each of them to help identify the expected scope.
  • Review the entire tree with respect to your targets, budget, timelines, processes, resources and select those RS Activities which will or might be part of the initial release.
  • Organize all of these RS Activities into a Functional Tree for the initial release.

This tree is the basis for your initial release negotiations. Your goal is to take this Release Contents and refine it. Some activities will stay in the Release Contents. Some will move into the next release WBS. Some will be split into current and next release activities. But in the end, you have a proposed Release Contents functional tree.

Project Management

The next step is for the project manager to assign each activity to the manager responsible for producing the functional specification for that RS activity. The manager and staff should be able to do an accurate sizing on the activity (+/- 50% assuming a reasonable number of activities) and should be able to identify dependencies between activities where applicable.

At this point, the project manager can roll up the estimates and identify more clearly the total effort to achieve the initial release. Required release dates and available resources/budget will dictate whether or not you need to chop things from the Release Contents. This is a negotiation that will be done primarily between the Product Manager and the Project Manager. If you're serving primarily one or two customers, they would be involved as well. The negotiated Release Contents document forms your Product Requirements for your initial release.

Functional Spec - Contract and Driver

At this point in time, each activity is fleshed into a functional specification by the assigned resource. Reviewers are assigned to each activity and reviews are tracked against each specification, perhaps as an appendix or in a parallel data field. A final round of sizing is performed and a more accurate effort estimate results. This is the first and most important phase of the development. Ideally, the functional specifications may be attached directly to each activity. The entire tree gives a functional specification for the entire release.

Make sure that your functional specification is correct. If you need to do some exploratory work to eliminate specification risk, do it as part of the specification phase. When you come out of the specification phase, you should not have any significant risk remaining. Perhaps a few resource allocation issues to deal with, perhaps a backup strategy or two to cover still risky areas. But there should be no show stoppers.

Implementation

From the functional specification, testing, documentation and implementation may proceed in parallel. With respect to the WBS, this means creating 3 new kinds of activities. Test plans should be attached to testing activities, design documents should be attached to implementation activities, documentation strategies should be attached to the documentation activities. Ideally, each area will help the other. If something is too complex to document, perhaps a specification change can be proposed to simplify the operation. Test beds, and perhaps test cases may be made available for the developers to exercise their completed components. Developer-designed white-box test cases may be collected into a white-box test case suite.

These activities are all streamed to a particular release. They should be added to the tree in such a manner that clear traceability exists, either by hierarchical organization, or by explicit reference to the activities spawning them. Execution of the activities by the assignees yields the raw components for the initial release. A number of system integration, verification and configuration management activities should help to yield the actual release. The WBS captures all of these activities and shows them in a hierarchical manner.

The product test cases you develop to test the initial release should trace back to a WBS activity (i.e. a Product Requirement). Perhaps you'll have white box test cases which reference design activities. The change packages for the initial release that you use to create or change your code should reference a WBS activity. In any event, you should have full traceability from your change packages through to your requirements. Your test cases and changes should clearly belong to the stream for which they were performed. Your code branches, likewise, should belong to the stream for which they were created. If some of these artifacts remain unchanged in subsequent streams, they should be shared by those streams.

The requirements, test cases, documentation, code and perhaps other artifacts require 2-dimensional version control: stream and revision within each stream. The WBS does not require 2-D version control. It, by definition, is a single stream entity. It's defining the transformation operation to take your product from point zero to release 1. Then next one goes from release 1 to release 2, and so forth. Then you may have 2 more WBS structures to go to release 2.1 and to release 3 in parallel.

Your activities and changes all are targeted to a particular release development stream. If an activity does not get completed in one release, it should either be moved to another stream (and WBS) or split into the portion that is completed and the non-compliant portion, the latter going into another stream. Your changes may be applied to more than one stream. But in that case a separate change package should appear in each stream if there are any file revisions not shared between streams.

Your completed WBS is invaluable. Not only does it give you traceability and documentation. It also contains metrics such as what portions of the product development schedule were consumed by requirement specifications, design, test cases, CM, etc. If planned and actual information is maintained for each activity, you also get valuable feedback on your estimation process. You have a history of who worked on what parts of the release. It forms a basis for moving from CMM/CMMI level 4 to level 5.

Some Requirements Management CM Guidelines

Here are a few of the Requirements Management guidelines I consider important from a Configuration Management perspective.

  • Requirements need full version control, both by revision within a product development stream and branching into other product development streams.
  • Requirements, perhaps even more that source code, need change control and traceability. Requirements should not be changed ad hoc and the reasons for the changes need to be documented.

  • A related set of changed requirements due to a single request, for example, should be grouped together in a requirements change set, just as related files of a source code change should appear in a change package.
  • Requirements are different than files so they should be treated differently. Normally, a requirement is expressed as a paragraph or a few paragraphs. There shouldn't be the overhead of having to manage a file and a workspace in order to change such a paragraph. So version and change control of these requirements should be possible without the need for a file to do the revisioning. Of course files should be permitted as well, especially as references, attachments, diagrams, etc. and these themselves may need to be under separate version and change control.
  • Requirements don't need to be named in the same way that files are. It is far more convenient to give them titles and to let the CM/RM tool generate the unique id for the requirement.
  • Requirement numbering should not be at the mercy of it's position in the requirements tree. It should be easy to identify a requirement through all revisions of the requirements document.
  • Requirements need to be organized into a tree. It's fine to let the tree identify paragraph numbering, but this should be different from the identifier of the requirement, as the position will change over time.
  • Requirements trees need version control just as directories do in the source code world. It is not sufficient to simply generate the Requirements Document and to revision control that. If you do, all of your questions such as "what's different between these two releases of the requirements document" become textual responses, as opposed to data responses which can be used to further extend your query and data navigation.
  • Requirements trees need to be baselined, just like source code. However, release of a baseline to the development environment needs to be much more clearly controlled. Visibility is one thing, marching orders is another, especially if you're changing directions.
  • You need to be able to trace from changes made to the source code back to the requirements that have been addressed. From a testing perspective, you want to trace test cases back to requirements, but you also want to trace test results back to requirements. This is why it's really critical, I feel, that your end-to-end data reside in a common repository, and ideally is accessible through a single tool.

I've not really tried to introduce a lot of new concepts here. Instead, I've tried to focus on making product development a "stream-based" process and on using the WBS for more than a simple project management tool. It's not necessarily an easy process to move to such an all-inclusive WBS capability, but it's a target to be reaching for if you want to improve your process maturity.


Joe Farah is the President and CEO of Neuma Technology. Prior to co-founding Neuma in 1990 and directing the development of CM+, Joe was Director of Software Architecture and Technology at Mitel, and in the 1970s a Development Manager at Nortel (Bell-Northern Research) where he developed the Program Library System (PLS) still heavily in use by Nortel's largest projects. A software developer since the late 1960s, Joe holds a B.A.Sc. degree in Engineering Science from the University of Toronto.

You can contact Joe by email at farah@neuma.com