Capturing Requirements with Use Stories

The title should describe an activity

The title of the story, “Account Holder withdraws cash”, describes an activity that the account holder wants to carry out. Until we implement this feature, the account holder won’t be able to withdraw money from the ATM. Once we have delivered it, they will. That gives us an obvious starting point for determining what “done” looks like.

If we had a title like “Account management” or “ATM behaviour”, we would have to look harder to understand when we were finished, and the edges would be a lot more fuzzy. For instance, “account management” might incorporate applying for a loan, and “ATM behaviour” might encompass changing the PIN number on my cash card. The story title should always describe actual behaviour by a user of the system.

The narrative should include a role, a feature and a benefit

The template “As a [role] I want [feature] so that [benefit]“ has a number of advantages. By specifying the role within the narrative, you know who to talk to about the feature. By specifying the benefit, you cause the story writer to consider why they want a feature.

It gets interesting if you find the feature won’t actually deliver the benefit attributed to it. This usually means you have a missing story. There is one story with the current feature, which delivers a different benefit (and is therefore still useful), and a hidden story whereby you will need a different feature to deliver the benefit described.

The example story tells us there is an Account Holder who cares about the feature being delivered, so we know where to start exploring what it should do.

The scenario title should say what’s different

You should be able to line up the scenarios side by side, and describe how they differ using only the title. In our example, we can see that the scenario descriptions say only what’s different between each scenario. You don’t need to say “an account holder withdraws money from an account with insufficient funds and is told they are unable to fulfill the transaction”. It’s obvious from the title whether this is the scenario you care about, compared to the others.

The scenario should be described in terms of Givens, Events and Outcomes

This is the single most powerful behavioural shift I have seen in teams adopting BDD. Simply by getting the business users, the analysts, the testers and the developers to adopt this vocabulary of “given/when/then”, they discover that a world of ambiguity falls away.

Not all scenarios are this simple. Some are best represented as a sequence of events, described as: given [some context] when [I do something] then [this happens] when [I do another thing] then [this new thing happens] and so on. An example is a wizard-style website, where you step through a sequence of screens to build up a complex data model. It is perfectly appropriate to intermingle sequences of events and outcomes, as long as you get into the habit of thinking in these terms.

One interesting emergent behaviour is that the quality of the conversation changes. You will quickly discover that you have missed out an assumed given (“well of course the account is overdrawn”), or forgotten to verify an outcome (“well naturally the account holder gets their card back”). I observed this on one particular project where the lead developer told me he could sense the analysts and developers were talking at cross purposes, but couldn’t see a way to demonstrate this to them. Within a few days of introducing the given/when/then vocabulary, he could see a dramatic improvement in the quality of their interactions.

The givens should define all of, and no more than, the required context

Any additional givens are distracting, which makes it hard for someone looking at the story for the first time – whether from the technical or business side – to understand what they need to know. Similarly any missing givens are really assumptions. If you can get a different outcome from the givens provided, then there must be something missing.

In the example, the first scenario says something about the account balance, the card and the ATM itself. All of these are required to fully define the scenario. In the third scenario, we don’t say anything about the account balance or whether the ATM has any money. This implies that the machine will retain the card whatever the account balance, and whatever the state of the ATM.

The event should describe the feature

The event itself should be very simple, typically only a single call into the production code. As discussed above, some scenarios are more complicated than this, but mostly the scenarios for a story will revolve around a single event. They will differ only in the context (the givens) and the corresponding expected outcomes.

The story should be small enough to fit in an iteration

There are no hard and fast rules about how you do this, as long as you break it down into demonstrable chunks. In general if there are more than about five or six scenarios, a story can probably be broken down by grouping similar scenarios together.

We can’t tell from the ATM example how many more scenarios there are for this story, but I am suspicious that there may be several more. Essentially we have three “moving parts” in this story, namely the account balance, the status of the cash card and the state of the ATM. We could get into more detail with the cash card: what if it is out of date, so I can’t use it to withdraw cash but the ATM still returns it to me? What if the ATM breaks partway through the transaction? What if my account has an overdraft facility?