Elements of Requirements Style, Part 3

Requirements & Requirements Management

Elements of Requirements Style, Part 3

By |

One of the most common types of requirements problem is missing information. Either entire requirements could be absent—which are hard to spot, being invisible—or individual requirements are missing information that help make them fully comprehensible. In this article I’ll present some examples of both kinds of problems, along with some recommended solutions.

Omissions

When requirements lack important bits of information, it’s hard for all readers to interpret them in the same way unless they make precisely the same assumptions. For instance, a functional requirement might describe a behavior without identifying the triggering cause that leads to that behavior:

The system shall generate an error report and forward it to the user.

This requirement doesn’t identify the stimulus that leads the system to produce the error report. Another common mistake involves missing descriptions of how possible exceptions should be handled. In the previous example, what should happen if no errors occur during the processing being described? It’s unspecified, thereby leaving it up to the developer to decide what to do. Options include:

  • Do nothing (an assumed default perhaps).
  • Present a “Congratulations! No errors found.” message but do not generate a report.
  • Generate an empty report and forward it to the user.
  • Generate a report stating that no errors were found and forward it to the user.

Perhaps we add the following requirement to address the case in which no errors are encountered:

If parsing is successful, the system shall not generate an error report.

This is another description of the system doing nothing, though, as I discussed under “Negative Requirements” in a earlier article in this series. It would be better to state what the system will do if no error is encountered, even if it is to simply continue the processing.

Another kind of incompleteness occurs when requirements describe system behaviors that involve some type of symmetry. Suppose you’re specifying the functional requirements for a bookmark feature in a Web browser. You might say:

The system shall display the user’s defined bookmarks in a collapsible hierarchical tree structure.

So, the user can collapse the bookmark tree, but what if he wants to expand it again? It’s easy to overlook that sort of symmetrical or reverse operation. To remedy this, either you could add a second requirement stating that the tree can be expanded, or you could alter this requirement to say “…in a collapsible and expandable hierarchical tree structure.”

If you omit the reverse operation, the customer and the BA might assume that the missing portion of the symmetrical requirement is implied. If you request an undo capability, of course you want a redo capability as well, right? But implicit requirements make me nervous. They involve too many assumptions about the knowledge and thought processes that other stakeholders must have to ensure that we all get what we expect in the final product. I know of a organization that developed its own tool for editing and storing source code in a database, with no written requirements. Unfortunately, they forgot to include the ability to print the contents of the database. The team members no doubt assumed that a printing function would be included so didn’t even think to mention it. They didn’t mention it, and they didn’t get it.

Boundaries

Boundary values in numerical ranges provide additional opportunities for creating ambiguity, as well as being places to look for missing requirements. Suppose you’re writing software for a point-of-sale system and you need to comply with a business rule that states, “Only supervisors may issue cash refunds greater than $50.” An analyst might derive several functional requirements from that business rule, such as the following:

  1. If the amount of the cash refund is less than $50, the system shall open the cash register drawer.
  2. If the amount of the cash refund is more than $50 and the user is a supervisor, the system shall open the cash register drawer. If the user is not a supervisor, the system shall display a message: “Call a supervisor for this transaction.”

But what if the amount of the cash refund is exactly $50? Is this a third, unspecified case? Or is it one of the two cases already described? If so, which one? Such ambiguity forces the developer either to make his best guess or to track down someone who can answer the question definitively. This is an example of the BA generating an inconsistency between a higher-level piece of information—the business rule—and the functional requirements derived from it.

You can resolve boundary ambiguities in one of two ways. The previous requirement #1 could be rewritten as, “If the amount of the cash refund is less than or equal to $50, the system shall open the cash register drawer.” This preserves the original intent of the business rule and eliminates the ambiguity.

Alternatively, you could use the words inclusive and exclusive to explicitly indicate whether the endpoints of a numerical range are considered to lie within the range or outside the range. To illustrate with a different example, you might say, “The system shall calculate a 20% discount on orders of 6 to 10 units, inclusive.” This wording makes it perfectly clear that both endpoints of the range, 6 and 10, lie within the range subject to the 20-percent price discount. You still need to review a set of similar requirements to make sure the range endpoints don’t overlap, though. For example, note the inconsistency between the following two requirements:

  1. The system shall calculate a 20% discount on orders of 6 to 10 units, inclusive.
  2. The system shall calculate a 30% discount on orders of 10 to 20 units, inclusive.

The boundary value of 10 is incorrectly included in both ranges. Using a table to show this sort of information is more concise and makes these kinds of errors more evident:

Units Purchased Discount Percentage
1–5 0
6–10 20
11–20 30
21+ 40

Also read Elements of Requirements Style, Part 1

Also read Elements of Requirements Style, Part 2

Also read Elements of Requirements Style, Part 4

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.

Karl Wiegers
Latest posts by Karl Wiegers (see all)