How Detailed Should Requirements Be? (Part 3)

Requirements & Requirements Management

How Detailed Should Requirements Be? (Part 3)

By |

In the previous article in this series, I described several conditions in which writing less detailed requirements is appropriate. However, there are several situations in which recording only high-level requirements information increases the project’s risk. When you encounter situations such as the ones described in this article (adapted from my book More about Software Requirements), expect to spend more time than average developing detailed requirements specifications.

Development will be outsourced

Anytime you outsource software construction rather than performing it in house, your project will benefit from comprehensive requirements documentation. When the developers are a continent or an ocean away, you don’t have the opportunity for the day-to-day interactions needed to flesh out the details, answer questions, and resolve ambiguities. In certain cultures, software developers will implement precisely what the client specified, even if it’s not complete or sensible. Without having many opportunities for clarification, you have no choice but to supply all the necessary information in the form of written specifications and acceptance tests. Do your best to remove uncertainties before sending the specification out for implementation.

Project team members are geographically dispersed

It takes surprisingly little separation between project participants to inhibit communication. I learned this long ago when I was writing programs for a research scientist who sat just a few feet from my desk. One day John moved to a new office about a hundred feet away. My productivity dropped immediately. It now took longer to get my questions answered. I had to set up a meeting with John, phone him, or walk down the hall and hope to catch him, whereas previously I just had to call out my question to get an immediate response. It was an eye-opener for me to see the impact that even a small distance between developer and customer had on my productivity. If you’re concerned about having customer representatives available to supply the missing details during design and construction, you’d better produce that information during requirements development.

On another project, the three of us collaborating on a project worked in two different buildings. We didn’t have a written requirements specification. Instead, we held a weekly meeting to focus our efforts for the next week, and then we went off and did our own parts of the work with limited interaction. On at least two occasions, one developer wasted a full week of effort because we all walked out of our meeting with different understandings of what we were supposed to do that week. Even a limited SRS will reduce this sort of waste, as will closer and more frequent collaboration among the project participants.

Testing will be based on requirements

If testers will be writing comprehensive system tests or user acceptance tests from the requirements, they must know just how the system is supposed to behave under various circumstances. In fact, the concept of “testable requirements” has been proposed as a measure of software size.
Tests should cover not only the expected behavior, but also the known exception or error conditions that can arise. Therefore, the requirements specifications need to describe these exceptions well enough so that testers can determine whether the software is functioning correctly. You likely won’t think of all the possible exceptions, but identifying potential problems and specifying how to handle them leads to a more robust product.

Accurate estimates are needed

Project managers or developers who must generate effort and schedule estimates from requirements need enough detail to understand what they’re getting into. I once saw an innocent-looking “functional requirement” that stated: “The XML editor shall respond to editing directives entered by voice.” The way the SRS was written gave no hint that this one item was profoundly more complex than the other 700 functional requirements in the document. That simple statement implied the need for an entire speech-recognition engine and interface! It’s difficult to estimate the cost of implementation without decomposing that high-level statement into enough detail to get a good handle on its size, complexity, and difficulty.

Requirements traceability is needed

Requirements tracing is the act of creating logical links between individual functional requirements, their origins (such as use cases, stories, product features, or business rules), and the work products the team creates to satisfy each requirement. Such downstream work products include design elements, source code, test cases, and help screens. If requirements tracing is important to your project, you need to specify the requirements in detail.

Evidence of requirements traceability is needed for certain safety-critical products, such as those that require U.S. Food and Drug Administration or Federal Aviation Administration (FAA) certification. For instance, the FAA’s safety standard DO-178B specifies that “every line of code be directly traceable to a requirement and a test routine, and that no extraneous code outside of this process be included in the build.” Traceability information ensures that your system has no orphan code and no overlooked requirements. Requirements traceability confirms that following conditions are met:

  • All requirements trace forward to elements of the software design.
  • Each design element can be traced back to specific requirements.
  • All code written traces back to a design element and hence to a requirement.
  • All requirements are implemented in the code.
  • Test cases exist for each requirement.
  • All test cases trace to at least one requirement.

If you’re in a regulated industry, you already know if you need to implement traceability as part of your requirements management activities. Otherwise, the choice is yours. Successful requirements tracing requires some time, discipline, a process to make it happen, and a tool in which to store the data. You might conclude that it’s a waste of time for your project. Before you do, though, consider an insightful comment made by the CEO of a major corporation when I discussed traceability while teaching a requirements course at his company. He asked, “Why wouldn’t you do this for all of your mission-critical systems?” He got it.

Also read How Detailed Should Requirements Be? Part 1

Also read How Detailed Should Requirements Be? Part 2

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.

Karl Wiegers
Latest posts by Karl Wiegers (see all)