{"id":3340,"date":"2013-06-21T09:00:57","date_gmt":"2013-06-21T16:00:57","guid":{"rendered":"https:\/\/www.jamasoftware.com\/?p=3340"},"modified":"2023-01-12T16:56:53","modified_gmt":"2023-01-13T00:56:53","slug":"how-detailed-should-requirements-be-part-3","status":"publish","type":"post","link":"https:\/\/www.jamasoftware.com\/legacy\/blog\/2013\/06\/21\/how-detailed-should-requirements-be-part-3\/","title":{"rendered":"How Detailed Should Requirements Be? (Part 3)"},"content":{"rendered":"

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\u2019s risk. When you encounter situations such as the ones described in this article (adapted from my book\u00a0More about Software Requirements<\/em>), expect to spend more time than average developing detailed requirements specifications.<\/p>\n

Development will be outsourced<\/strong><\/p>\n

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\u2019t 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\u2019s 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.<\/p>\n

Project team members are geographically dispersed<\/strong><\/p>\n

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\u2019re concerned about having customer representatives available to supply the missing details during design and construction, you\u2019d better produce that information during requirements development.<\/p>\n

On another project, the three of us collaborating on a project worked in two different buildings. We didn\u2019t 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.<\/p>\n

Testing will be based on requirements<\/strong><\/p>\n

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 \u201ctestable requirements\u201d has been proposed as a measure of software size.
\nTests 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\u2019t think of all the possible exceptions, but identifying potential problems and specifying how to handle them leads to a more robust product.<\/p>\n

Accurate estimates are needed<\/strong><\/p>\n

Project managers or developers who must generate effort and schedule estimates from requirements need enough detail to understand what they\u2019re getting into. I once saw an innocent-looking \u201cfunctional requirement\u201d that stated: \u201cThe XML editor shall respond to editing directives entered by voice.\u201d 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\u2019s 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.<\/p>\n

Requirements traceability is needed<\/strong><\/p>\n

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.<\/p>\n

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\u2019s safety standard DO-178B specifies that \u201cevery 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.\u201d Traceability information ensures that your system has no orphan code and no overlooked requirements. Requirements traceability confirms that following conditions are met:<\/p>\n