Category Archives: Requirements management software

Software used or designed to be used for managing requirements. We look at individual applications and what they can do, as well as features or use cases that drive what those applications should do.

Requirements Document Proliferation

too many documents

Too many companies don’t document their requirements.

Worse still, too many companies over-document their requirements.

Roger Cauvin and Cote’ have started a great conversation about the proliferation of requirements documents. To follow the thread, start with Roger’s post, make sure you read the comments there as well. Then check out the post by Cote’.

The main point that they are making is that having 4 levels of requirements document is ridiculous. The four levels (shown in more detail in their posts) are:

  1. MRD – Market requirements document – used by marketing people. Describes the needs of the market, like “Driving downtown takes too long. There’s a need for a better solution”
  2. PRD – Product requirements document – used by product managers. Describes what a product must be capable of doing, in order to address the needs of the market, such as “Transporter must move people from rural areas to downtown in less than half the time of driving.” From the wikipedia definition, we see that the PRD has much of the same content as an FRS.
  3. FRS – Functional requirements specification – used by program managers*. Describes the same thing that a PRD does. Personally, I’ve never seen both used on the same project. Here’s a good definition of an FRS at mojofat.
  4. SRS – Software requirements specification – used by software developers. Describes the same thing that an FRS does. Here’s a good explanation of what’s in one from MicroTools, Inc.

Many people get so frustrated with all of these different ways to document requirements that they either look for a novel approach (or another here), or declare that requirements are counter-productive. The problem gets exacerbated when a bunch of former technologists attend a training class and start preaching the importance of (pick one of the docs above) without an understanding of the big picture. The current software-development outsourcing trend in the US has forced a lot of people to scramble to find new homes in the org chart. Cote’ is spot-on with his application of Conway’s law to this problem.

Cote’ suggests that we need a single person/team that “does it all”, flattening the hierarchy. Several people commented on a post here about CRUD requirements, and the discussion touches on a similar issue- drawing the line between requirements and design. Some of those folks came to the same conclusion. And I agree, when we can find supermen who can write code that solves valuable problems (which they identify), we can have great software. When we have to collaborate as a team of specialists, we need to include requirements documentation to get the best return on our investments.

I do disagree with Cote’ that some of these layers of documents exist to enable people who aren’t “technical enough” to participate. Different people play different roles, and care about different information. Communicating with these people, in their language, is critical.
question mark

What the heck should we do?

  1. Understanding the needs / problems in the market is critical to succeeding. The build it and they will come illusion of the late 90’s has been broken. Only the companies and products that provided real value survived that shakeup. Should we document those market needs? Yes. Is an MRD the right document? Probably. Roger knows more about this than I do, and he and other folks I respect believe in the MRD. If you don’t, at least codify your understanding of the market somehow – maybe this way.
  2. Building a vision for software that addresses those needs is critical to success. I left a previous employer with a philosophy tatoo that is stuck in my head like a bad song from the 80’s (Oh Mickey, you’re so fine…). That phrase is filler versus killer – and it was applied to every proposed feature for new software. Are those filler features that just take up space and time, or are they killer features that solve real problems and provide real value? Creating a software-vision designed to address market needs is an ideation process. And it should be documented. PRD, FRS, SRS – a rose by any other name. When forced to choose, I would call it a PRD, because in practice it is harder to avoid writing about implementation details than it is to avoid overlapping with market needs.
  3. Designing software that achieves that vision is critical to success. We can’t leave out design. Agile approaches work well because (among other things) they do even more design – it just isn’t all “up front”. Regardless of what process you choose, build and document a design based upon the requirements.

Executive summary: Document market needs in an MRD. Document requirements for your software in a PRD. Document your designs.

Managing requirements conversations

In Documents vs. Conversations, on the Pyre blog, Greg Wilson does that thing that we so rarely do – he takes a step back, and thinks from an entirely different perspective about managing requirements. He proposes the idea of managing requirements as conversations, instead of as documents.

Greg makes the point that the reason for managing requirements is not to create a document, but rather to communicate. He points out that no one can have an omniscient awareness of the entire spec, and therefore people operate based on an understanding of a subset of the spec at a given time. And since the evolution of the spec happens by conversation, he proposes a conversation-centric view of the requirements. Greg points to the successful examples of open source software development teams driving feature delivery from conversations.

Jerry Aubin of Seilevel, posts about context in their blog, Requirements Defined. The focus of Jerry’s post is on the conversations that drive the creation of use cases.

Conversations are most relevant while a spec is being defined. After the spec is defined, the conversation is less relevant – determining the genesis of a requirement is less important than determining the relevance of a requirement (i.e. which use case does it support, how does it help to achieve ROI, when will it be delivered). The primary beneficiary of a conversational analysis is the requirements manager, who benefits only in that it provides organizational context, which helps when defining a subset of the specification.

As Greg pointed out, we interpret subsets of the specification at a point in time. Writing of the specification also happens piece-meal. Once a portion of the spec has been written, the conversation that occurred starts to immediately lose its relevance. When internal teams are responsible for distilling the inputs from multiple conversations with multiple customers, then conversational models will help the product managers, but only until the spec is written – then the conversation becomes an (infrequent) reference.

When managing requirements for customer-specific software, a conversational model will have even less benefit. A discrete set of customers must approve a set of requirements or a statement of work. In these cases a document-centric model will be more effective.

There is definitely value in helping a product or program manager to manage and mine multiple conversation threads as part of forumulating a spec. Changing the tools we use to manage the resultant specs would be a step backwards, imho. Once the evolving spec is actionable, the consumers of the spec will still benefit from a contextual presentation. I would suggest using a tool like OneNote to collect and organize the information that comes from multiple sources (email, IM, hallway conversations, whiteboard discussions, etc). The custom tagging and search capabilities due to be introduced in Windows Vista could also be leveraged to make conversation management more effective.

Communicating a delivery schedule with use cases

Use cases are a great tool for establishing the scope of a project. They provide a framework for defining what needs to be implemented (if it doesn’t support a use case, we don’t need to implement it). They also set expectations with stakeholders (here’s what you can do with the system).

Many teams fail to leverage use cases to communicate a delivery schedule.

Quick tangent on why incremental delivery is good

When we deliver a project incrementally, we have to think about it in terms of delivering the features needed to support atomic use cases. If we deliver three of the four features required for a particular use case, then users can’t perform the use case. If users don’t perform the use case, then we won’t generate the return on the investment. Use cases are the key to scheduling incremental delivery.Note that a product release roadmap may be driving a high level schedule of functionality, and that roadmap will be driving the schedule of completed (enabled) use cases.

Communicating schedule with use cases

Setting expectations with users and other stakeholders requires that we communicate the schedule of delivery for our software. Stakeholders don’t think or care directly about when feature X is enabled. Feature X is implicitly worthless. When a user can perform a particular use case, which depends upon feature X – that’s what they care about. The executive who funded the project cares about when the business will see a financial benefit from using the software, which is achieved through a set of use cases, which in turn depend upon feature X. Why do so many project, product, and program managers try and communicate scheduling to this audience in terms of features? We should speak the language of the listener.

When talking about the schedule to a user, we should talk about the schedule of particular use cases.

On a large project last year, we were managing requirements using Caliber RM, where we maintained use cases and functional specs with tracing between them. This project was for a very large enterprise software deployment, and it had over 50 use cases with about a dozen different primary actors (classes of users of the system, like regional salespeople, financial accounting people, etc). We were also managing the project across multiple quarterly releases. We needed to set expectations with multiple stakeholders at different levels of the organization, and we had a global development team working on the project from multiple locations.

We needed to present a clear and concise report that would show which use cases were enabled in each release of the software. We were maintaining all of the data in Caliber RM, and the dynamics of the project were such that we were regularly reprioritizing and rescheduling features for upcoming releases. We also wanted to spend our time managing the project, not the reporting on the project, so I built some automation to generate a table showing the schedule for use cases.

The information you want to show in the report is easily understood in a matrix, where each row represents a use case, each column represents a particular actor, and each cell represents the release in which the actor can begin performing a particular use case. This view of the information also helped us in planning rollout and user training schedules. A table of this information could look something like this:

With the schedule, we were able to easily reconcile interdependence of use cases in particular workflows (for example, creating an order is valueless without the ability to approve an order). We were able to plan the rollout to users (corporate accounting would not use the system before Q3). Our development managers were able to view a high level schedule when planning deliveries and our consultants were able to plan for anticipated loading of the servers.

Best of all, we were able to set expectations and provide a roadmap for our stakeholders, who needed a simple way to grasp the very complex product roadmap for delivery. Our communication with executives was at a higher level – reviewing schedules at the goal level, but interacting with different subject matter experts and other mid-level managers often included this view, which was very helpful.

When creating packaged software for consumers or businesses, the same approach is invaluable for planning and can be used to generate excitement in the users. While developed for enterprise software delivery, it is easily applied to shrink-wrapped and hosted software deployments with multiple customers.