Recently I was chatting at a wine tasting event with a couple of lawyers, who I had just met. One was surprisingly inquisitive about my work in the software requirements arena. Apparently she was working on case involving software at that very time. At one point she asked me, “How do you know how detailed to make the requirements?” It’s an insightful question, one that even experienced business analysts often ask me.

There’s no single correct answer to this question, even assuming we could agree on exactly how to measure requirements “detail.” This is one of those thorny issues that plague BAs. For most such issues, the correct answer is, “It depends.” Despite being true, that’s not a very satisfying reply. Even though there is no simple answer to this simple question, I can give you some ways to think about how much detail is appropriate in a given situation. This is the first in a series of three articles adapted from my book More about Software Requirements (Microsoft Press, 2006). The second article will describe situations in which you can safely get away with less detail, and the final article points out situations where including more detail is a good idea.

Who Makes the Call?

The central question to consider when deciding how detailed to make the requirements is: Who do you want to have making the decisions about requirements details and when? If you’re willing to defer many of the ultimate decisions about product capabilities and characteristics to the developers, you don’t need to include as much information in the requirements documentation. This can also work if appropriate customer representatives are available to work with developers to pin down the details and make the necessary decisions at construction time. However, if you want to describe exactly what you expect to be delivered, more complete specifications are necessary.

As with many decisions made on software projects, you need to balance cost and risk. It costs more to develop requirements in greater detail than to leave them more high-level. Choosing the appropriate amount of detail to include depends upon how risky it is to leave decisions about requirements specifics to developers to make later in the development cycle. The main risk we’re concerned about is having to perform extensive and unplanned rework late in the project or iteration to create a satisfactory product. Nor do you want to hear a developer say, “Gee, if I’d only known more about this requirement two months ago, this would have been easy to implement. Now I have to redo some of what I’ve already built.”

Let me give you an illustration about requirements detail. My house has a security alarm system. When the alarm is set and I enter the house, the alarm starts beeping at me. To disarm the system, I enter my passcode on a numeric keypad. At one level, we could state a requirement for this function quite simply: “When the alarm system is armed and a sensor is triggered, the user shall be able to enter a numeric passcode to disarm the system.” This statement conveys the general intent, but it isn’t enough information for the developer to know just what to design and build. Here are some questions that arise when considering the implications of this requirement:

• What are the minimum and maximum numbers of digits allowed in a passcode? Does it have to be numeric?
• How should the system conclude that the user has finished entering the passcode so it can evaluate the entered code?
• How can the homeowner set and change his passcode? Is there a default?
• How long does the system wait for the user to enter the correct passcode before it sounds the alarm?
• What does the system do if the user enters an incorrect passcode before the timer runs out?
• How many entry attempts does the user get? Or perhaps it’s a function of time: Can the user make as many attempts as he likes within a fixed time interval?
• If the user enters the wrong passcode, does the timer reset to zero or does the countdown continue toward sounding the alarm?
• What does the system do if the user does, or does not, enter the correct passcode within the specified time interval?

Clearly, someone has to answer these questions. If the BA doesn’t supply this sort of high-resolution information in the requirements specification, the responsibility falls to the developer. He has to identify all the pertinent questions and either track down the answers or make decisions based on his own judgment. If you’re the BA, you need to decide on the most appropriate approach. Do you want developers to come up with answers for such questions on the fly at design and construction time? Or would you rather have customers and subject matter experts record the necessary information in the requirements specification? It’s your call.

Customers sometimes balk at taking the time to think through these kinds of issues carefully and make decisions. My response to this hesitation is to ask the customer, “If you don’t want to make these decisions now, who do you think should make them and when?” Developers sometimes are comfortable with vague and incomplete specifications, because that gives them the opportunity to interpret the requirements however they want. However, it pays to remember one of my Cosmic Truths about Software Requirements: “The requirements might be vague, but the product will be specific.” The central issue is who the specificity comes from.

Figure 1 identifies some situations in which you need more detail in the requirements documentation and other cases where less rigor will suffice. In the next two articles in this series, I’ll discuss these various conditions in more detail.

Implied and Assumed Requirements

No requirements specification can ever fully describe a product. Nor should you ever expect written documentation to replace human dialog. Still, I get nervous when I hear people talk about “implied” or “assumed” requirements.

It’s risky to assume that everyone who reads the requirements specification will know exactly what is intended without the BA spelling it out. For example, it’s not reasonable to think that every reader will automatically know which system functions require the user to be logged in and which do not. It’s unrealistic to expect every reader to distinguish those parts of the system that demand particularly rapid response times—and to know just what those response times should be—from the parts that don’t have specific performance expectations.

Quality requirements also dictate many architectural choices. If those high-impact requirements aren’t written down because the people with that knowledge assume that others share their insight, the product could fail to meet expectations for performance, reliability, integrity, and so forth. An expensive rework project then might begin, building a new architecture to try to meet the demands of the operating environment.

Consider this philosophy: “If it’s not in the specification, do not expect to find it in the product.” As with all philosophies, this extreme position needs to be tempered by reality. If you attempt to create a totally inclusive specification, you’ll spend the rest of your life writing requirements and won’t have any time left to build products. At the other extreme, some project teams are reluctant to write down the requirements. But documentation’s not the hard part. The hard, time-consuming part is figuring out what the requirements are. Recording them is mostly transcription at that point.

My preference is to err in favor of writing down anything you aren’t certain that the reader will know. Don’t rely on telepathy and clairvoyance as the technical foundations for your project. They don’t work.

Also read How Detailed Should Requirements Be? Part 2

Also read How Detailed Should Requirements Be? Part 3

Jama Software has partnered with Karl Wiegers to share licensed content from his books and articles on our web site via a series of blog posts, whitepapers and webinars.  Karl Wiegers is an independent consultant and not an employee of Jama.  He can be reached at http://www.processimpact.com.  Enjoy these free requirements management resources.