How Detailed Should Requirements Be? Part 3 - When More Requirements Detail Is Advisable


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.

Author: Karl Wiegers is Principal Consultant at Process Impact, His interests include requirements engineering, project management, peer reviews, and process improvement. His most recent book is a memoir of life lessons titled Pearls from Sand: How Small Encounters Lead to Powerful Lessons (

Like this article:
  6 members liked this article


Marc Thibault posted on Wednesday, December 14, 2011 12:49 PM
The example functional spec provides an excellent illustration of the flaw in functional specs and the reason we've moved to use cases.

Instead of being buried in 700 other disconnected statements, voice input would have been front and center on every use case that included user input.

Making every developer comb through the entire functional spec in case somewhere in that morass there's something that affects what he's building is a peculiar form of punishment that we're well rid of.

Marc Thibault posted on Wednesday, December 14, 2011 12:52 PM
As to the strain of separation - you have to have good use cases anyway but we now have tools for shrinking distance. I've worked in environments that included people on three or four different continents using tools like GoToMeeting, Skype and just about everything Google serves, that puts everyone and their screen moments away.

One of the pleasant surprises is that meetings in cyberspace are generally more productive than in meatspace.
Karl Wiegers posted on Wednesday, December 21, 2011 11:28 AM
@marcthibault: The distance collaboration tools you describe are certainly a huge improvement over what has been available in the past. However, they still involve some level of scheduling and coordination. It's just not the same as being able to get an immediate response to a question from someone that you can see is in the room at the moment. The agile folks often talk about the importance of having "on-site" customers. I prefer to spell it "on-sight." Obviously, it's not always feasible to have all the key stakeholders in the same room at the same time, so any collaborative mechanisms like the ones you suggest are a big plus.

I am also a big fan of use cases. However, in my experience of using use cases for about 17 years, and having collected the experiences of hundreds of practitioners through my training seminars, I have found that UCs are not a substitute for detailed requirement specifications in many cases. You can choose to organize the functional requirements in ways that are more accessible than a traditional functional specification, or you can store them in a requirements management tool. Nonetheless, use cases often do not contain sufficient detail to prevent developers from having to ask a lot of questions and track down a lot of missing information. I prefer to employ use cases as a mechanism for understanding user requirements, rather than as the ultimate requirements deliverable in most cases.
dieseldaddy posted on Tuesday, January 29, 2013 2:41 PM
I agree and fully believe in "distance shrinking" tools such as skype and web-based collaboration...however those only work when you have customers who are in a desk-oriented worksetting. I work with scientific labs and other departments where they are 90% or more AWAY from their desk. Never underestimate the need for face-to-face communication when gathering requirements.
Only registered users may post comments.



Copyright 2006-2024 by Modern Analyst Media LLC