Business Analyst Community & Resources | Modern Analyst

How Detailed Should Requirements Be? - Part 1

Featured

55013 Views

15 Comments

45 Likes

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).

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.

The figure below 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.

Less Detail Needed

More Detail Needed

Customers are extensively involved

Developers have considerable domain experience

Precedents are available

Package solution will be used

Development will be outsourced

Project team members are geographically dispersed

Testing will be based on requirements

Accurate estimates are needed

Requirements traceability is needed

Some factors that influence how much requirements detail is needed.

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.

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

Posted in: Requirements Analysis (BABOK KA), Elicitation (BABOK KA), Requirements Management and Communication (BABOK KA)

45 members liked this article

Featured

55013 Views

15 Comments

45 Likes

Crafting Valuable Requirements Using Business Architecture and Artificial Intelligence

Requirements vs. User Stories: Which Are Better?

Priming: A Powerful Tool for Business Analysts

What Requirements Are Needed When Implementing a COTS Information System?

COMMENTS

Nícolas posted on Sunday, November 13, 2011 6:05 AM

Hi Karl,

I was pleased to read your post, and my BA side wants to contribute to it.

I really think that "detailing requirements" is the less important task to a BA do. In the other hand "define/refine the most important requirements" is the most important task to a BA do.

But who should do the requirements details? I venture to say: nobody. Do we really need these requirements detailed? Can we specify these requirements in a way that it's a mirror of the product? Can I replace the communication between the team and the client with a comprehensive documentation?

I think the best way to test your understanding over a requirement is delivering this requirement.

The table "Less detail needed vs More detail needed" have some arguments defending the detailed requirements, but lets think about them:

* Development will be outsourced
Even if the development will be outsourced, the team (developers/designers) must to communicate with the client. Nothing replaces a conversation between team and client.

* Project team members are geographically dispersed
When you are working with distributed teams, you have to change your mindset about communication. Detailed requirements will not make the team work closely. The team still have to communicate.

* Testing will be based on requirements
If we are talking about a developer doing BDD, this is the moment for a focused conversation between the team and the customer about a requirement. There is no need of a previous detailed documentation about the requirements to write tests, one focused conversation is enough.

* Accurate estimates are needed
Estimatives is a another big problem. Do you ever finished a project in time? Does somebody in the world achieved this? I work giving small estimatives based on the requirements I'll work for the next week.

Nícolas posted on Sunday, November 13, 2011 6:05 AM

Karl Wiegers posted on Sunday, November 13, 2011 9:55 AM

@nicolasiensen: Thank you for your comments. You said: "But who should do the requirements details? I venture to say: nobody." My point is that somebody will *always* decide what the detailed requirements are. Whether or not you document those somewhere is a separate question.

When you are in a situation (lack of adequate customer access, outsourced or distributed development, etc.) that inhibits your ability to have frequent clarifying discussions, then there will inevitably be communication gaps and misunderstandings, so someone else will have to fill in the gaps and guess as best they can. I frankly don't understand the resistance to writing requirements. IMHO, the hard part isn't writing the requirements: it's determining them. I couldn't disagree more that "one focused conversation is enough" to ensure that testers will adequately understand requirements well enough to do adequate testing. If that works for you, though -- great!

Tony Markos posted on Monday, November 14, 2011 10:27 AM

Hi Karl:

Insightfull article! Another angle to consider: How integrated should the process/functional requirements be? Higher level of abstraction requriements that are strongly focused on the essential interrelationships (i.e., data flows) are going to be of much more value than a bunch of disjointed detail level requirements.

Tony

Karl Wiegers posted on Monday, November 14, 2011 10:38 AM

@Tony: I agree.This is one reason I am a fan of use cases. They provide one level of organizational structure for a set of logically related detailed functional requirements. I'm also a huge believer in modeling, which as you point out, represents requirements knowledge a higher level of abstraction.

Too many analysts begin the elicitation process by asking users "What do you want?" Or "What are your requirements?" Such useless questions invite random -- yet important -- input that lacks any organizational scheme that lets you see how the pieces fit together. I call the resulting list of disjointed functional requirements a "pile" -- important, but not terribly useful, easy to work with, or easy to analyze for completeness and correctness.

Ovidiu posted on Tuesday, November 15, 2011 5:24 AM

Hi Karl,

This is a very interesting topic. It was on my mind a lot lately too. I think an important point that was not addressed is the distinction between business requirements and system requirements / design. Both of them can be detailed, and how detailed do you want each to be?

In your example, this is the business requirement, and it's a high-level one: “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.” It has a goal that when reached brings value to your customer (in this case security comfort).

The details of your example are, in my opinion, actually detailed system requirements or some would say, even design items. To me, a requirement should always identify a need that when satisfied brings value. I often find people asking all sort of questions about details (especially related to non-functional requirements) which do not answer the business aspect (what is the actually value of having this?). We can define in detail all sorts of parameters and targets that we do not know if are really needed, but this effort could be better spent trying to identify the business needs (the whats whys instead of hows).

There is a common misconception that business requirements should be high level, while system requirements are detailed. In my opinion, this is a grave mistake. I would rather spent time identifying the various needs of stakeholders (which can be very specific), instead of defining a system into detail. Once you have the detailed business requirements, it's very easy to define the system to fulfill them. You can even let the developers decide the system design as long as it fulfills the described business targets.

This is the reason why I tend to favor user stories to use cases. User stories identify stakeholders and reasons (needs) by definition, while use cases usually describe system-user interaction which in the end might bring no value if not properly analysed and traced back to business requirements.

What do you think?

Ovidiu

Karl Wiegers posted on Tuesday, November 15, 2011 9:42 AM

@Ovidiu: Your question immediately reveals one of the fundamental problems we have in the world of software requirements: terminology. You are using the term "business requirement" in a different way from how I use it. I don't have space to go into all of my requirement definitions here, but you can read about them in chapter 1 of my "Software Requirements, 2nd Edition" book. In my terminology, the business requirement is something like to secure the home against entry by unauthorized individuals. I consider the requirement that I showed in my article and the list of questions following to relate functional requirements (what you are referring to is "system requirements"). These describe specific system behaviors under particular conditions.

As you point out, I agree that it's essential for user requirements and functional requirements to align with achieving specific business requirements. My point is that there is a great deal of latitude around exactly how specific to make the functional requirements.

Ovidiu posted on Tuesday, November 15, 2011 10:10 AM

I think we are actually talking about the same thing. I will just call functional requirements what I previously called system requirements.

My point was that from my experience, people tend to spend too much time to define functional requirements and much less to define business requirements. However, functional requirements do not provide any business value when delivered, unless they fulfill some business requirement(s). What I've often seen to happen is that some analysts spend just a few days in understanding the business needs, stakeholders and the context and much more in defining detailed functional requirements. Many assumptions are made this way.

What I'm trying to say is that, in my view, requirements analysis includes much more investigation than engineering. The engineering part is just a formalization and organizing of what has been investigated. It should not include any specific design. Sometimes the line between functional requirements and design is too fuzzy, but I think functional requirements should focus on what the system needs in order to fulfill the business requirements.

In conclusion, I would say that business requirements should almost always be detailed, while functional requirements may be more or less detailed, based on various factors (as you mentioned in the article).

Karl Wiegers posted on Tuesday, November 15, 2011 2:34 PM

@Oviduiu: I agree with you that it's vital to understand the business objectives, product vision, project scope, and limitations to make sure that the product built achieves the organization's business objectives. I also agree with you that this is something organizations often skimp on, to their detriment. However, I would expect a BA to spend a lot more time on eliciting and specifying user requirements and and functional requirements than on business requirements, simply because of the larger quantity of material. You might state one particular concise business objective for the project that leads to a massive amount of functionality that needs to be explored, understood, and documented in an appropriate amount of detail.

But you're absolutely right: you can do a fabulous job of specifying functional requirements and implementing them, but if the resulting product doesn't achieve your business requirements, then you missed the mark.

jennab posted on Thursday, November 17, 2011 9:57 AM

Love it! My favorite parts “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.” and the follow-up point… “I would expect a BA to spend a lot more time on eliciting and specifying user requirements and functional requirements than on business requirements, simply because of the larger quantity of material. You might state one particular concise business objective for the project that leads to a massive amount of functionality that needs to be explored, understood, and documented in an appropriate amount of detail.” When I am training or providing feedback to new BA’s I suggest they focus on eliciting the details of the functional requirements, not what “section” of the document they will go in, it will be far better to capture the information somewhere than to spend time worrying about what kind of requirement they have identified. I find that the people who really care what section the requirement belongs in will let you know where they would rather see the words place. A healthy combination of conversations and documentation (be it requirements, user stories, use cases) are where I feel there is the greatest value in requirements development. If we “err in favor of writing down anything you aren’t certain that the reader will know.”, then as a BA that may not be there to support the thing 6 months after it is in production, and no one remembers exactly how the thing was supposed to work, I will know that I can direct them back to the documentation.

John Warren posted on Saturday, November 19, 2011 8:48 AM

Dear Karl,

Thank you for your stimulating article “How detailed should requirements be?” At risk of adopting a provocative position, I would like to suggest that they should be “completely detailed”, by which I mean “sufficient to support automated proof”. I believe that several of your points are answerable from this perspective. I have made abbreviated quotations from your article in what follows.

I start from the position that one good form of requirement specification is a model of the intended system. I suggest that we carry out the requirement process with meticulous attention to detail, probably with reasoning tools to assist us. And we should seek every possible chance to ensure that the requirements we capture are correct.

Who do you want to make the decisions about requirements details? You may trust the developers to take “detailed” decisions. You may place customer representatives with the developers to make the necessary decisions. If the requirement is not complete in detail, then you are saving “requirements” money by leaving others to make decisions later in the development; the risk is that there may be additional “implementation” costs through unplanned rework later in the project.

I suggest that it is well worth spending time ensuring correct and detailed requirements for at least the following reasons:
1. Implementation usually costs more than requirement analysis.
2. Errors cost more to fix the later we discover them in the project life cycle.
3. Several reports suggest unstable requirements contribute to project failure.
Customers sometimes baulk at taking the time to think carefully and take specific decisions; the response is to ask “If you don’t want to make these decisions now, who should make them and when?” Developers should never be comfortable with vague or incomplete specifications; no developer should ever “interpret” requirements but should be concerned only to “implement” the requirements given.

I endorse entirely the “more detail needed” conditions. If we outsource or disperse implementation effort, then developers need to know precisely what to develop. We should naturally base testing on requirements; insufficiently detailed requirements will lead to insufficiently detailed testing. If we need accurate estimates, then we need the detail on which to base these. And if we need requirements traceability, then detailed requirements must be present initially.

No requirements specification can ever fully describe a product. This statement will be correct for a range of “non-functional” requirements, such as quality, performance, integrity, and reliability. However, I assert that for functional requirements, it is perfectly feasible to write an inclusive specification. And for functional requirements, I support the philosophy “If it is not in the specification, it will not be in the product.”

I should declare an interest or bias at this point: I believe in provable software. I admit that proof is difficult. In practice, we can achieve this only through automated reasoning; proofs are otherwise too long and too complex. But proof is more powerful than testing in assuring quality software (though testing is still needed); I accept as a corollary that proof requires the provision of more detail than would otherwise be needed. And I assert that the quality of provably consistent, demonstrably correct specifications and the derivative code is very high.

In practice, my experience is that the additional detail is not excessive and offers major advantages. All of these arise from the ability to reason about the requirement specification. One advantage is the ability to test requirement specifications for correctness at the requirement stage by deducing the actual behaviour from that which you defined in the specification. Another advantage is the ability to deduce the complete operational code thereafter, entirely automatically.

In summary, we need good (precise, consistent, correct) requirements with sufficient detail to support automated proof. We need requirement tools to allow us to generate provable requirements easily. We need reasoning tools to reason about the requirement specifications we generate. We need proving tools to prove the properties of the systems we produce. And we still need testing tools, to undertake requirements-based testing, to show to users (and ourselves) that the system really does work in the manner intended!

John Warren

Rwittick posted on Saturday, November 19, 2011 10:04 AM

Hi John,

I would like to bring out another aspect of Requirements i.e, dynamic nature which goes beyond the business needs and the skill required to generate precise, consistent ,correct requirements specifications. Without doubt a Process exists within the Requirements team that determines and details requirement to a level that helps the developer to create and aids testing team to perform valuable tests. However if the process does not leave room for evolution of a requirements that fulfills one feature or sets of same, trouble brews in the delivery stages of product development cycle. Even if the Business requirements are changing or the complexity of the product increasing ,time and again has shown that by bringing flexibility in structure of requirements, the dyanmic needs are well addressed and creates far lesser rework especially in cross functional teams. A change itself cannot be predicted always during requirements analysis. But the cost of implementation can be bought under control if the requirements are flexibly structured. Communication is the key when it comes for the BA or requirements writer to convey a change in requirements. However its the structure of a requirement that actually constrains the communications.

How Flex should a requirement be? That depends is the most appropriate answer. However the larger picture of flexibility in requirements is more visible in the context of inter-relationships among requirements . When a developer sees requirements talking to each other then the purpose of Requirements process is truly met to achieve a business need or fulfill a feature.

Rwittick(Rick)

John Warren posted on Saturday, November 19, 2011 12:49 PM

Dear Rick,

I agree wholeheartedly! And thank you for your response.

The dynamic nature of requirements, which needs to support business needs in a rapidly changing world, is important. We start with an “analysis” or discovery activity during which we assemble a lot of possibly disparate facts. We later follow this by a separate “synthesis” activity in which we “try to make sense” of our discovery. We record the outcome in a suitably flexible structure or architecture. And of course, we often iterate between these two activities before we reach a final solution. As you correctly say, this must leave room for evolution and change.

Most systems involve inter-relationships amongst and between requirements; certainly this is my experience over a wide range of different projects. This is one factor, amongst others, that makes requirements engineering an interesting and challenging discipline. I strongly endorse your view that when “requirements talk to each other” then we are well set to “achieve a business need” and we already embody this principle in the tools we use.

Almost all systems are subject to change and enhancement throughout their working life; the only stable system is a dead one. So the post-delivery part of the life cycle is at least as important as the initial development; possibly more so, if you consider that it is harder to change one part of a system without adversely affecting other parts. It is here that the structural flexibility of the requirements is of prime importance, as you point out; and I suggest that a rigorous analytical approach to any requested change will be equally important.

John Warren

Tony Heap posted on Wednesday, December 7, 2011 3:17 AM

Great article!

I used to document system functionality to a precise and complete level of detail, in the belief that I was creating an unambiguous specification which would also serve as a useful record for future use.

But over time I observed that (a) developers can often sensibly fill in the blanks (with or without direct conversations) and (b) people rarely referred to my "record" after the project was delivered, preferring to get their answers directly from the dev/support team or from the live system itself, due to a desire to be absolutely sure of getting an accurate answer.

Over time I've changed my approach and now I only document to the level that I feel necessary to get the job done.

One gotcha though is forgetting to provide enough detail for the testing team. If you leave blanks in the spec for the dev team to fill, the problem then is that the testers don't know what is "right" and therefore what tests to run. On recent projects, the people asking me to add more detail to the spec have been the testers, not the developers. Despite agile approaches advocating automated testing, I don't think we are ready to do away with manual testing completely yet - and I'm not sure I have a good answer to this problem. .

Karl Wiegers posted on Wednesday, December 7, 2011 9:39 AM

@Tony: I agree that the optimum approach is to "document to the level that I feel necessary to get the job done." That is more sensible and pragmatic than either extreme position. This is a judgment call.

As you suggest, it's vital that the BA remember that there are multiple audiences for the requirements spec, and numerous "jobs" to get done based on that information. Your point about the testers needing more detail is very important. Writing a minimal spec can cause a lot of problems if the developers and testers make different assumptions about fleshing it out. Even though the developers might make sensible choices about the missing details, they need to communicate this knowledge to the testers somehow. Otherwise, a lot of time gets wasted.

Only registered users may post comments.