{"id":3344,"date":"2013-06-17T08:36:05","date_gmt":"2013-06-17T15:36:05","guid":{"rendered":"https:\/\/www.jamasoftware.com\/?p=3344"},"modified":"2023-01-12T16:56:54","modified_gmt":"2023-01-13T00:56:54","slug":"how-detailed-should-requirements-be-part-1","status":"publish","type":"post","link":"https:\/\/www.jamasoftware.com\/legacy\/blog\/2013\/06\/17\/how-detailed-should-requirements-be-part-1\/","title":{"rendered":"How Detailed Should Requirements Be? (Part 1)"},"content":{"rendered":"
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, \u201cHow do you know how detailed to make the requirements?\u201d It\u2019s an insightful question, one that even experienced business analysts often ask me.<\/p>\n
There\u2019s no single correct answer to this question, even assuming we could agree on exactly how to measure requirements \u201cdetail.\u201d This is one of those thorny issues that plague BAs. For most such issues, the correct answer is, \u201cIt depends.\u201d Despite being true, that\u2019s 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<\/i> (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.<\/p>\n
Who Makes the Call?<\/h2>\n
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?<\/i> If you\u2019re willing to defer many of the ultimate decisions about product capabilities and characteristics to the developers, you don\u2019t 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.<\/p>\n
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\u2019re 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, \u201cGee, if I\u2019d 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\u2019ve already built.\u201d<\/p>\n
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: \u201cWhen the alarm system is armed and a sensor is triggered, the user shall be able to enter a numeric passcode to disarm the system.\u201d This statement conveys the general intent, but it isn\u2019t 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:<\/p>\n
\n
What are the minimum and maximum numbers of digits allowed in a passcode? Does it have to be numeric?<\/li>\n
How should the system conclude that the user has finished entering the passcode so it can evaluate the entered code?<\/li>\n
How can the homeowner set and change his passcode? Is there a default?<\/li>\n
How long does the system wait for the user to enter the correct passcode before it sounds the alarm?<\/li>\n
What does the system do if the user enters an incorrect passcode before the timer runs out?<\/li>\n
How many entry attempts does the user get? Or perhaps it\u2019s a function of time: Can the user make as many attempts as he likes within a fixed time interval?<\/li>\n
If the user enters the wrong passcode, does the timer reset to zero or does the countdown continue toward sounding the alarm?<\/li>\n
What does the system do if the user does, or does not, enter the correct passcode within the specified time interval?<\/li>\n<\/ul>\n
Clearly, someone has to answer these questions. If the BA doesn\u2019t 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\u2019re 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\u2019s your call.<\/p>\n
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, \u201cIf you don\u2019t want to make these decisions now, who do you think should make them and when?\u201d 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: \u201cThe requirements might be vague, but the product will be specific.\u201d The central issue is who the specificity comes from.<\/p>\n
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\u2019ll discuss these various conditions in more detail.<\/p>\n
Figure 1. Some factors that influence how much requirements detail is needed.<\/p><\/div>\n
Implied and Assumed Requirements<\/h2>\n
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 \u201cimplied\u201d or \u201cassumed\u201d requirements.<\/p>\n
It\u2019s 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\u2019s 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\u2019s unrealistic to expect every reader to distinguish those parts of the system that demand particularly rapid response times\u2014and to know just what those response times should be\u2014from the parts that don\u2019t have specific performance expectations.<\/p>\n
Quality requirements also dictate many architectural choices. If those high-impact requirements aren\u2019t 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.<\/p>\n
Consider this philosophy: \u201cIf it\u2019s not in the specification, do not expect to find it in the product.\u201d As with all philosophies, this extreme position needs to be tempered by reality. If you attempt to create a totally inclusive specification, you\u2019ll spend the rest of your life writing requirements and won\u2019t have any time left to build products. At the other extreme, some project teams are reluctant to write down the requirements. But documentation\u2019s not the hard part. The hard, time-consuming part is figuring out what the requirements are. Recording them is mostly transcription at that point.<\/p>\n
My preference is to err in favor of writing down anything you aren\u2019t certain that the reader will know. Don\u2019t rely on telepathy and clairvoyance as the technical foundations for your project. They don\u2019t work.<\/p>\n
![\"\"](\"https:\/\/static.jamasoftware.com\/www\/imports\/2013\/06\/a50f1.png\")