Requirements Management

How Detailed Should Requirements Be? (Part 2)

By |

In the first article in this series, I pointed out that there’s no easy answer to the question of how detailed the requirements need to be. Instead, I can present a thought process the business analyst can use to assess the appropriate level of detail for each case. As I describe in this article, which is adapted from my book More about Software Requirements, several conditions make it appropriate to leave the requirements descriptions at a higher level of abstraction. Recognize that these are broad guidelines. The BA should perform a risk-benefit analysis to balance the potential downside of omitting important information against the effort required to include it.

Customers are extensively involved

If you have extensive, ongoing, and intimate involvement by the right customer representatives, you can get away with less written requirements documentation. This is the premise behind the on-site customer in agile development methodologies. In such situations, developers need just enough written information about requirements to estimate their size and get a general idea of the customer’s intent. The details will come later from conversations with customer representatives and subject matter experts.

This approach works only when developers have ready access to customers who have the time, knowledge, and authority to make decisions on behalf of the communities they represent. Even if the customers can provide just-in-time details, it’s doubtful that anyone will record those details. This makes it harder to reach a shared expectation among the various stakeholders. Your project might lack a written reference to ensure that the product is adequately tested and that no requirements were inadvertently overlooked during implementation. Of course, you can capture the requirements details as the developers obtain them, thereby growing the requirements specification—or, as in some agile approaches, the suite of acceptance tests—incrementally.

Developers have considerable domain experience

Developers with extensive application domain knowledge can sometimes supply a lot of the necessary requirements details. Watch out for developers who are overconfident, certain that they understand what users need without asking. Ideally, knowledgeable representatives of specific user classes will work with the BA to develop requirements.

There’s always a risk of a disconnect when using surrogates who will not actually use the product being developed. Technically sophisticated developers might not be representative of the typical end user. Even developers with a lot of domain experience sometimes aren’t aware of the current needs in a changing business environment. If their knowledge is obsolete, they can’t do a good job of supplying the missing requirements.

If developers are filling in a lot of the requirements details, it’s a good idea to have them run their ideas past the BA and some customer representatives before implementing them. A simple review provides a check to make sure the fleshing out is being done appropriately.

Precedents are available

When precedents are available to use as a model, you don’t need to include all the requirements details in the specification. The developers can turn to the existing product or documentation as a reference for details that aren’t provided in the current specification. This might be the case when reengineering a legacy application, for example.

Watch out, though. Most software contains extensive functionality that is not immediately visible to someone who is simply looking at the user interface or a high-level product description. Some examples are exception handlers, business rule enforcement, and relationships between data in fields on a form or dialog box. You don’t want every developer to have to reverse-engineer the existing product to figure out just what it does, possibly arriving at different conclusions.

A package solution will be used

Projects that plan to acquire a commercial package solution for all or part of the functionality don’t need highly detailed requirements. There’s no point in writing comprehensive functional requirements, because 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 must specify the requirements for package extensions, integrations, and customizations.

Use cases are an effective requirements elicitation technique for package-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 package to another (functional requirements and user interface design). User acceptance tests based on use cases are also helpful for evaluating packages. Knowledge of the pertinent business rules is critical. The package you select must enforce the necessary business rules and let you change or customize them as necessary. Defining quality attribute requirements will also help the stakeholders choose the right package.

Sample Levels of Requirements Detail

Let’s return to the home alarm system example I mentioned in the first article in this series. Following is an illustration of how you might write some functional requirements for disarming the triggered system. The first requirement (our original one) is written at a high level:

Disarm.Alarm 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.

A developer who receives this requirement likely will have many questions. The table below shows how the BA could flesh out this high-level requirement with additional specific functional requirements, if the BA judges that this is a good idea. (These requirements are written in a traditional hierarchical format, expressed using a compact notation to give each child requirement a unique identifier, such as Disarm.Alarm.Timeout.Siren. The parent requirement, Disarm.Alarm, is shown as a title or heading, rather than as a discrete requirement statement.)

Disarm.Alarm: Disarming the triggered system with a user-entered passcode
       .Sound When a sensor is triggered after the system is armed, the alarm system shall emit an intermittent warning tone. The alarm system shall sound the tone until either the system is disarmed or the preset warning duration has passed.
       .Interval The system shall evaluate an entered passcode 1.0 second following user entry of the last digit. Digits entered within less than 1.0 second of the previous digit’s entry are appended to the sequence of passcode digits the user has already entered.
       .OK If the entered passcode is correct, the system shall stop emitting the warning tone and shall set itself to the disarmed state.
       .NoGood If the entered passcode is incorrect, the system shall continue to emit the warning tone, continue counting down the warning duration, and permit the user to reenter the passcode.
       .Timeout If the warning duration is reached before the user enters a valid passcode, the system shall take the following actions:
             .Siren Trigger the alarm system’s siren.
             .Dial Dial the alarm system monitoring company.
             .Log Record the alarm incident in the internal system event log.

Note that these requirements include the names of some data objects, like “warning duration” and “passcode.” I recommend that you collect the meaning and attributes of such objects in a data dictionary, a separate document (or file) or an appendix to the requirements spec. The data elements and structures that pertain to the requirements are defined and hierarchically decomposed in the data dictionary.

Even though these functional requirements answer many of the questions posed earlier in this chapter about the alarm system’s behavior, they’re still missing some important information. What is the cycle frequency of the “intermittent warning tone” described in requirement Disarm.Alarm.Sound? How loud is it? What does it sound like? I’ve never seen a requirement that didn’t have opportunities for improvement. Whether to specify these details in the requirements or leave them to the developer’s judgment is the BA’s choice.

Also read How Detailed Should Requirements Be? Part 1

Also read How Detailed Should Requirements Be? Part 3

Jama Software has partnered with Karl Wiegers to share licensed content from his books and articles on our web site via a series of blog posts, whitepapers and webinars.  Karl Wiegers is an independent consultant and not an employee of Jama.  He can be reached at http://www.processimpact.com.  Enjoy these free requirements management resources.

Latest posts by Karl Wiegers (see all)