Karl Wiegers
Aug 26 · 10 min read

Recently I was chatting at a wine tasting with two lawyers I had just met. One was working on a case involving software. 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 wrestle with.

There’s no single correct answer to this question, even assuming we could agree on exactly how to measure requirements “detail.” As with many such questions, the correct — but not very satisfactory — answer is: “It depends.”

Though I can’t give you a simple answer to this very important question, I can suggest some ways to think about how much detail is appropriate in a given situation. This article is adapted from my book More About Software Requirements.

Who Makes the Call?

The central question to consider when deciding how much information to include in your 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 refined decisions about product capabilities and characteristics to the developers, you can write less requirements documentation. This can also work if customer representatives are available to work with developers to pin down the specifics and make the necessary decisions at construction time. However, if your key stakeholders need a shared expectation of what will be delivered, consider producing a more complete specification.

As usual, you need to balance cost and risk. Scanty or verbally communicated requirements cost less than if you write requirements in greater detail, but they do pose some risks. The main risk we’re concerned about is having to perform extensive, unplanned rework to create a satisfactory product. I hate rework.

A Real Example

Here’s an illustration about requirements detail. My house has a security alarm system. When the alarm is armed and I enter the house, the alarm’s control panel starts beeping at me. To disarm the system, I enter my passcode on a numeric keypad.

We could state a requirement for this function quite concisely: “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 lacks enough information for the developer to know just what to design and build. It leaves some questions unanswered, including these:

  • What are the minimum and maximum numbers of digits allowed in a passcode? Must it be numeric?
  • How should the system conclude that the user has finished entering the passcode so it can evaluate the entered code?
  • 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? Perhaps it’s a function of time: can the user make multiple attempts within a fixed time interval?
  • What does the system do if the user does, or does not, enter the correct passcode within the specified time interval?
  • How can the homeowner set and change his passcode? Is there a default?

Clearly, someone has to answer these questions. If the requirements set doesn’t supply this high-resolution information, the responsibility falls to the developer. He must identify all the pertinent questions and either track down the answers or make his own best judgment, which might or might not be what the customer had in mind.

If you’re the BA, you need to choose the most appropriate approach. Do you want developers to come up with answers for such questions on the fly at design and construction time? If they guess wrong, they’ll get to rebuild the system. Or would you rather get the necessary information from customers and record it in a requirements specification (which is also helpful for testers)? It’s your call.

Customers sometimes balk at taking the time to think through these kinds of issues carefully and make decisions. My response 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 like minimal specifications, as it gives them a lot of latitude regarding how to interpret the requirements. However, remember one of my Ten 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.

Figure 1 identifies some situations in which you need more detail in the requirements documentation and other cases where less rigor will suffice. The next sections discuss these conditions in more detail.

Figure 1. Some factors that influence how much requirements detail is needed.

When Less Requirements Detail Is Appropriate

Several conditions make it appropriate to leave the requirements descriptions at a higher level of abstraction. The BA should perform a risk analysis to balance the potential downside of omitting important information against the effort required to record it.

Customers are extensively involved. Ongoing and close collaboration with the right customer representatives can replace comprehensive requirements documentation. Developers need just enough written information to estimate each requirement’s size and get a general idea of the customer’s intent. The details will come later from conversations with customers and subject matter experts.

This approach works only when developers have ready access to people who have the time, knowledge, and authority to make decisions for the communities they represent. Even if the customers can provide just-in-time details, failing to write down those details makes it harder for the various stakeholders to know what to expect. Of course, you can opt to record the requirements details as they’re discovered, growing the requirements incrementally and easily.

Developers have considerable domain experience. Developers with extensive application domain knowledge can sometimes supply much of the necessary requirements detail. Watch out for developers who are overconfident, certain that they understand what users need without asking. Even developers with domain experience sometimes aren’t aware of the current needs in a changing business environment.

Precedents are available. When precedents are available to use as a reference, developers can turn to the existing product or documentation for absent specifics. This might be the case when reengineering a legacy application, for example. Watch out, though. Software often contains considerable functionality that isn’t visible to someone who’s simply looking at the user interface or at a high-level product description. Don’t force every developer to reverse-engineer the current system to figure out everything what it does.

A packaged solution will be used. There’s no point in writing comprehensive functional requirements if you plan to acquire a commercial packaged solution for all or part of the functionality; the package vendor has already done that (or so you hope). However, it’s rare that a package will fully meet your needs, so you still should detail the requirements for package extensions, integrations, and customizations.

Use cases and user acceptance tests are effective requirements techniques for packaged-solution projects. The package needs to let your users accomplish specific tasks (use cases), although the details of how this works will vary from one commercial package to another (functional requirements and UI design). The one you select must enforce pertinent business rules and let you customize them as necessary. Defining quality attribute requirements will also help the stakeholders choose the right commercial solution.

When More Requirements Detail Is Advisable

There are several situations in which recording only high-level requirements information can significantly increase a project’s risk. In such cases, expect to spend more time than average developing appropriately detailed requirements specifications.

Development will be outsourced. When the developers are a continent away from other project stakeholders, you don’t have the opportunity for the day-to-day interactions needed to flesh out details, answer questions, and resolve ambiguities. 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, and be aware of native language differences that could lead to confusion.

Project team members are geographically separated. It takes remarkably little separation between project participants to inhibit communication. Long ago 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, whereas previously I just had to call out my question to get an immediate response. If you’re concerned about having customers right on tap to supply the missing details, you’d better produce that information during requirements development.

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. This is especially important if testing will be performed by people who weren’t involved in the development work.

Tests should cover not only the expected behavior but also the known exception conditions that can arise. The requirements must describe these exceptions well enough so testers can determine if the product is handling them right. Identifying potential problems and specifying how to the system should respond leads to a more robust product.

Accurate estimates are needed. People who must generate effort and schedule estimates from requirements need enough information to understand what they’re getting into. I once saw an innocent-looking functional requirement — just one among about 700 for a large project — that stated: “The editor shall respond to editing directives entered by voice.” That simple statement implied the need for an entire speech-recognition engine and interface! It’s impossible to estimate the cost 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, and the work products that satisfy each requirement. If requirements tracing is important to your project, you need to specify the requirements in detail.

Certain safety-critical products, such as medical devices and aviation systems, must demonstrate requirements traceability before they can be certified for use. Traceability information ensures that your system has no orphan code and no overlooked requirements. It shows that several 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 have been implemented in the code.
  • Test cases exist for each requirement.
  • All test cases trace to at least one requirement.

If you work in a regulated industry, you already know if you need this sort of traceability data. Otherwise, the choice is yours. Successful requirements tracing requires some time, discipline, a process to make it happen, and a tool to store the data.

Sample Levels of Requirements Detail

Think back to the home alarm system example above, and let’s see how we might write some functional requirements for disarming the triggered system. Our original single requirement is written at a high level:

We saw some of the questions a developer who receives this requirement might have. The table below shows how the BA could flesh out this high-level requirement with more detailed functional requirements, if she believes this is a good idea. (These are written in a hierarchical format using a compact notation to give each child requirement a unique identifier, such as Disarm.Timeout. They’re written at the granularity of individually testable requirements. The parent requirement itself, Disarm, is shown as a title or heading, rather than as a discrete requirement statement.)

As with all requirements, these could doubtless be improved, but they clearly provide a lot more specifics than the original.

Even though these functional requirements answer many of the questions posed earlier in about the alarm system’s behavior, they’re still missing some important information. What exactly does the “warning tone” described in requirement Disarm.Sound sound like? How loud is it? Whether to specify such details in the requirements or leave them to the developer’s judgment at design time (with input and validation from the right customer, I hope) depends on who you want to make the decision: customer, BA, or developer.

Do your project’s requirements demand this level of detail? Or is a simple list of major functions adequate? That’s your call. Rather than guessing on the right level of detail, the BA and developers should work together to determine the appropriate amount of requirements specification. It’s all about risk. You don’t want to spend more time on requirements than necessary, but you don’t want to have to rebuild parts of the solution to get it right, either.

The Ultimate Message

Whenever you, your colleagues, or your customers balk at putting in the effort to document requirements, remember that the hard part is not writing requirements. The hard part is figuring out what the requirements are. Recording them is mostly thoughtful transcription at that point.

My preference is to write down anything you aren’t certain that the stakeholders will know, or anything you need to retain for future use. Don’t rely on telepathy and clairvoyance as the technical foundations for your project. They don’t work.

===========

If you’re interested in requirements and business analysis, Process Impact provides numerous useful publications and other resources.

The Startup

Medium's largest active publication, followed by +504K people. Follow to join our community.

Karl Wiegers

Written by

I’ve written on software development and management, consulting, self-help, chemistry, military history, and a mystery novel. More info at karlwiegers.com.

The Startup

Medium's largest active publication, followed by +504K people. Follow to join our community.

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade