«    »

Example-Based Requirements

Most of the requirements I deal with are in the form of documented use cases and lists of business rules. These requirements are almost always written in a generalized form. For example a business rule might be written as "Produce a warning if the last transaction in the account is more than a year ago."

A common problem I encounter from the use of these generalized requirement statements is ambiguity. This has multiple negative impacts. The user representatives providing requirements and the business analysts documenting them can both review the same written requirement and agree that it is correct, based on their discussions, while actually holding differing interpretations. But it gets worse. The developers implementing the requirement who typically do not have the benefit of the interactions and discussions with user representatives can arrive at an even larger range of interpretations. And if you have a separate tester, who knows what they might come up with.

To illustrate the problem, here are some questions about the example business rule provided above demonstrating the amount of ambiguity in just one single sentence:

  • By the phrase "last transaction" do you mean the last transaction chronologically? If so, which transaction date should be used to determine this – the date of posting or the date of acceptance?
  • The phrase "more than a year ago" could be based on calendar year or could be based on the corporate fiscal year. Which is it?
  • Assuming the phrase "more than a year ago" is calculated based on calendar year, how exactly should the calculation work? It could be based solely on the year – e.g. warn if the year of the transaction is two or more years less than the current year. It could be based on date – e.g. warn if the transaction date happens before the same month and day as today last year. Or it could be based on a number of days – e.g. warn if the transaction date is more than 365 days before the current date. (Note that the last two scenarios will produce different results in a leap year.)

The solution to the problem of ambiguity is to use examples. And not just a few examples here and there to support particularly complex requirements – requirements should be largely based on examples, with the generalized description simply providing the higher level intent or summary. Examples should ideally be created by user representatives, or at the very least carefully reviewed by them. The benefit of examples is not just to bring greater clarity to the development team but also to ensure the users are clear on what the system will do. This helps avoid unpleasant surprises when the users first see and play with the working system.

The Agile community has figured this out a long time ago, thus prompting the move to very short user stories supplemented with acceptance tests instead of formally elaborated use cases. The acceptance tests function as the specific concrete examples. The user story only provides a high level summary in part because of the expectation that further face-to-face conversation will take place regarding the requirement.

If your environment requires more formalized requirements documentation then keep using use cases and lists of business rules, but keep the written text focused on the higher-level intent while examples provide the specifics. To provide an example :) of this, here is the example business rule rewritten to fit this new approach:

As the account manager I want to receive a warning when the account has no recent activity.

  • Most recent transaction in account based on posting date of May 1, 2009 with current date May 1, 2010 produces the warning "No recent activity in account".
  • Most recent transaction in account based on posting date of May 2, 2009 with current date May 1, 2010 does not produce a warning.

If you find this article helpful, please make a donation.

3 Comments on “Example-Based Requirements”

  1. This article was originally part of the article Defect Prevention Practices.

  2. Michael Padberg says:

    Hi Basil,
    I have a small feature to add on to an app we built. having difficulties bringing the client and the developer, and me (today as BA) together to produce the right outcome. (not just the right requirements.) Im going to try your method described here and let you know how it goes.

  3. @Michael Great! I hope it works well for you. Let me know how it goes. One caveat: producing the right outcome is potentially a bigger problem than just having clear requirements. I’m not certain that example-based requirements will necessarily address your problem. It might be helpful if you provide an example :)

«    »