I’ve read many business, user, and functional specification documents and most of them read more like a story than something a developer can easily build code from. I can hear you already…”we have to provide the appropriate context for the system so the developers understand all that’s needed.” Yes, I agree, but I disagree with the way we convey that information.

Over the years I’ve coined two phrases relating to most requirements documents. They are “BTDs – Big Thick Documents” and “clumping.” BTDs are the typical outcome of most requirements development efforts. We’re very proud of our BTDs and we use them to fund our projects and demonstrate our understanding of the business needs. For these two purposes the BTDs will work, however, the BTD then gets handed to an architect or developer and that’s when things start to break down. Clumping is something we do within the BTDs. We’ll take multiple requirements and clump them together into a paragraph and then we’ll clump paragraphs together on a page, which ultimately creates our BTD.

The storytelling approach works pretty well from a business standpoint as most business people can easily relate to it. It’s written in a manner that contextualizes their business rules and process workflows, so they can typically read it and give us the nod that we understand them. This in turn gives us a false sense of security that we’ve done a good job of eliciting requirements. In reality we’ve only completed half the work of eliciting requirements.

What’s the rest of the story?

Although I’m an advocate of not writing in story format at all, let’s just assume for now that we continue to author requirements documents in that fashion, if for no other reason, so that our business people can easily relate to them. Once the BTD is done and the stories have been shared and agreed upon, i.e. signed off on, then we have to start the process of transforming the story into a structured list of categorized and hierarchically related requirements. Which is to say, we take BTDs full of clumps and turn them into requirements assets that can be clearly understood by developers, managed effectively in a tool, and reused in future projects. By doing this we extend the upfront limited business value of BTDs into long term business value in the form of requirements assets.

Is this really necessary?

Let’s walk a mile in the shoes of a developer. Developers are utilizing coding techniques that take the complexity of a system and turn it into small modular pieces of code. These code “objects” know how to talk to each other and can easily be interchanged and moved around. In order to build objects in this fashion the developers have to focus on very small aspects of functionality for a given object. Meaning they write code to satisfy a very small and specific piece of business functionality. Then they connect multiple objects together to create code that handles more complexity. Think of it this way; if all you needed the system to do was make sure that the user attempting to login has a valid user ID, then one fairly small piece of code will do. But if you want to actually validate their password, and then retrieve some information about them and then display the user’s homepage, etc., you’ll need lots of these code objects working together to accomplish this. But the foundation of the way code is written today is all about the small granular piece of code that tackles one very specific need. We connect lots of these together to build “the system.”

Compare this with the way most requirements documents are written and the problem quickly emerges. BTDs and clumps of requirements don’t align well with small discrete code objects. Add to this the natural subjective nature of written text and when the developer is tasked with digging through BTDs to figure out the code objects he needs to build, trouble is just around the corner. Let’s not even consider the language issues we may have with development teams spread over the globe.

Documenting requirements in story fashion really doesn’t require much more than note taking skills, and our business analysts have been called note takers for years. Where the skill of a business analyst is required is in the process of transforming BTDs with requirements clumps into structured, categorized, hierarchical lists of requirement assets that architects and developers can build systems from. I realize there are many elicitation techniques and skills, beyond that of note taking, necessary to create BTDs, but in the end if a BTD is all we deliver, we have not delivered real business value into the development process. Since the goal of software development is usable software not BTDs, we need to focus on the transformation process as much if not more than the BTD process.

The problem is that most business analysts and project management staff still believes that their job is done when the BTD is delivered. We’ve been doing it that way for years and we don’t have to look very close to see that the reputation of the business analyst and the impact of our BTDs on the development process are less than desirable. If you don’t believe me just ask most business partners how pleased they are with the software they received compared to what they expected to get.

How do we create requirements assets?

It can be argued either way as to whether or not we even need BTDs, but for this article we’ll assume they’re a given. That said, the transformation process requires the business analyst to tear apart the BTDs and develop requirements that depict small and specific aspects of the business, while maintaining the needed relationships between the requirements, so the proper context is retained.

To do this I recommend a minimum of four categories of requirements: Business, User, Functional, and Non-Functional or what I refer to as the Core Four. These requirement categories are well defined and documented in nearly all requirement books including Karl Wiegers’ book Software Requirements. In most organizations the BTDs are already somewhat categorized around the Core Four but, because of their story-like nature, even if it’s a Business Requirements BTD, it will still contain requirements that fall into other categories. As such, you can’t assume that a BTD labeled Business Requirements breaks apart into only the Business Requirements category.

In brief the Core Four are defined as follows:

• Business Requirements – defines the needs of the business and answers the question, “Why are we doing this?”
• User Requirements – depicts the system from the user’s perspective and answers the question, “What tasks do the users need to perform to satisfy the needs of the business?”
• Functional Requirements – defines the tasks that the system needs to perform and answers the question, “How must the system function in order to allow the user the ability to complete their tasks?”
• Non-Functional Requirements – defines the quality aspects of the system and answers questions like: How fast should it run? What color should it be? How many users must it handle? What security must it use?

At this point a Requirements Management tool becomes necessary. There are many on the market each with their pros and cons. The three or four that have been around the longest are: Requisite Pro – IBM, DOORs – Telelogic, CaliberRM – Borland, Optimal Trace – Compuware. Some of the newer ones hitting the market are: MKS Integrity for RM – MKS, Accept360 – Accept Software, Blueprint Requirement Center – Blueprint Software Systems, ContourRM – Xeau, iRise Studio – iRise. Many of which are built on current technologies and are browser based. Once a tool has been selected and implemented you can transform the BTDs into the Core Four and utilize the traceability feature of the tool to show the relationships between each requirement. This enables the story-like context to be retained, while providing valuable capabilities like impact and coverage analysis throughout the project.

This process of transforming BTDs into lists of requirements that are granular and specific in their definition, properly categorized within the Core Four, and contextually related to each other via traceability, is the heart and soul of what’s needed to help align requirements development with software development.