Why Write Software Requirements?

Does anyone ever read the bleeping requirements? Why do we even bother to write requirements if no one is going to read them?

I worked with a business analyst once who would get extremely frustrated when software developers would turn over code for testing and the software behaved, looked and flowed differently from what the requirements stated. The analyst’s favorite refrain was, “Did they even read the bleeping requirements?”

In truth, the developers almost always did read the requirements. Often, the developers had worked in the domain for many years. They had developed an intuition for the desires of the customer and had established a rapport with them. Changes were always made after the requirements were complete and simply not communicated back to the business analyst–the developers had become the analysts.

To these developers, the requirements were merely guidelines; starting points from which to build. Ultimately, the software created by these developers were accepted by the customers without complaint to the bafflement and frustration of the business analyst.

Keep in mind that we are talking about business applications in a custom development shop. This group of applications is much different than say an operating system or device driver. There is wiggle room here. Maybe not so in the other groups of applications.

Often, this same business analyst would spend a month or two creating a 50-100 page document fretting over every word and field placement and every screen title, menu option and work flow. The final document was impressive. When the business analyst finally let go of the document–notice I didn’t say finished–you’d think that the application was all but done and that there was no more requirements gathering to be done. However, something very important was forgotten . . .

One of my favorite comedians, Steven Wright, has a great joke that illustrates this. Here’s the joke:

I have a map of the United States…actual size. It says, “Scale: 1 mile = 1 mile.” I spent last summer folding it.
I also have a full-size map of the world. I hardly ever unroll it.

Now, we all know that Mr. Wright doesn’t really have a full size map of the United States. It’s simply impractical. Likewise, requirements can’t contain everything about the application before it is written. In an application of any complexity, there are always things that come up that no one could have anticipated.

In one of the best books on the requirements gathering process– “Exploring Requirements”, by Donald C. Gause and Gerald M. Weinberg–one of the very first points made is about the distinction between a map and the territory. Basically, the map is not the territory and, when in doubt, trust the territory.

That’s all these developers were doing. They were trusting the business domain territory. Of course, not every developer can be a domain expert; most aren’t. But just because a finished product doesn’t look exactly like the requirements doesn’t mean that the developers didn’t read the requirements. So, yes, they will read it. But no, they may not follow it to the letter.

So, do people really care about the requirements gathering process at all? Of course they do. The value of writing requirements is not in the end result though. People don’t sit back and look at the requirements and feel content that they’ve accomplished something that is going to be useful to the business. You’ve just finished starting. In terms of maps, you just plotted a course. The real work follows. Don’t be surprised when there are detours along the way. You should expect them.

The value of requirements then is in the doing; the gathering of information and exploring of the problem domain. This process can be daunting or easy depending upon the domain and the expertise of the people gathering the requirements. You must be careful not to get too caught up in the creative process of this though; you can easily waste valuable time.

Sometimes the gathering process can take months. A lot of knowledge is gathered in the processes that never makes it into the requirements but are crucial for the success of the project. These are the artifacts that still, in spite of being left out of the official requirements, somehow make it into the system anyway. These are the things that customers remember in conversations that make them happy when they see them.

I once worked on a project where analysts had been using UML Use Cases alone to capture requirements. It was very evident that they had never really built a large system before. The use cases, when printed out, fill three 5 inch binders. The diagrams looked like one-to-one connectivity matrices for a 1000 node network. I instantly nicknamed the tome “The Useless Cases”. That’s what they were. Almost 2 years had been spent on the effort and no one had a grasp on really what should be built–and nothing was.

I spent a few weeks with the domain experts (nurses) and created about 10 high-level DFD diagrams along with supporting English; something everyone could understand. The project took on a new life and when the investors came calling they were elated by what had been accomplished. As a result, we received new funding for the project. They weren’t impressed with the “The Useless Cases”.

That is one extreme of writing requirements. The other end of the spectrum is the paper napkin. This is what you’ll hear touted as Agile (I call it Fragile) and eXtreme programming (eXtremely NO requirements). The very few attempts that I have seen to adopt these new fads for requirements gathering yielded no better results. In the end, requirements were gathered, but, in a haphazard way that yielded functional results on a few occasions but with little gain over other methods I have employed.

Be sure, I’m not bashing RUP or Agile or eXtreme. There are elements to all of these approaches that are appealing when describing a problem to be solved. The key is to make sure that you don’t loose sight of why you are writing the requirements in the first place. So, let’s answer the question already . . .

We write requirements so that we are forced to think about the problem a little and map out a plan before actually creating the solution to the problem. Maps, like use case diagrams, stories, state diagrams, DFDs, IDEFs, class diagrams, ER diagrams and flow charts are only a part of the mapping. No single map is enough in itself for creating the solution. In the end you’ll need a collection of maps tied together with something I like to call English.

The solution to the problem . . . well, that’s in the writing of software–the territory. But that’s another blog . . .

5 thoughts on “Why Write Software Requirements?

  1. Requirements are definitely a road-map but not necessarily the destination.

    From my experience the best requirements were the ones that evolved through the interaction of all team members (DEV, BA, Business, etc) up until the last line of code was written.

    My biggest annoyance with requirements over the years has been some BA’s focus on document format more then the actual content and its usefulness. A requirement should be in any format that is best consumable by its intended audience, the developers! When this is lost and “process” overshadows “reality” things go very wrong.

  2. First of all, thanks for the terrific essay.

    Second, thanks for the plug of Exploring Requirements.

    Third, here’s a little tip that may help your readers keep all your lessons clear:

    – I never say “requirements” when what I’m talking about is a requirements document. “Requirements” are what the customers/business/organization/users require from the application. The document is just one possible map of that territory. There are many possible maps, and though all of them may be useful, no one (nor the entire collection) can fully and accurately capture the territory (the requirements).

    So, watch your language, and stay out of (some) trouble.

  3. One of the things that I have noticed as well is how personality affects requirements. Analysts tend to be passionate people and as such take the design and development of the system personally. Often times instead of hearing what the customer needs (notice I didn’t say wants :)) they tend to write requirements from the perspective of how they would want the system to work. I don’t know how many times I have gone to the analyst for requirements clarification and they gave me an answer off the top of their head without even checking with the customer. Being the “need to know for sure” guy that I am, I contacted the customer and got a completely different answer. Developers on the other hand tend to be more analytical in nature. They don’t think about themselves using the system but rather strive for the end result, the success of the effort. For them success is defined as positive feedback. The last thing a developer wants to hear from a customer is how crappy the application is.

  4. Nice article, I was looking for these kind of information on software development. Please continue writing….

  5. Hello,great post. Information are pretty exciting and saved me huge amount of time which I have spend on something else instead of searching posts like this. I am waiting for more.

Comments are closed.