In Part 1 of this series I discussed what user stories are and, as importantly, what they are not. In Part 2 I further explored how they are used as a collaboration tool. In Part 3, we look at why User Stories are not the requirements and propose a method for documenting them, if needed, given this assertion:
User Stories are not the requirements or the documentation and they die when they are done and are not updated.
“Stories aren’t a written form of requirements; telling stories through collaboration with words and pictures is a mechanism that builds shared understanding. Stories aren’t the requirements; they’re discussions about solving problems for our organization, our customers, and our users that lead to agreements on what to build. Your job isn’t to build more software faster: it’s to maximize the outcome and impact you get from what you choose to build.” ― Jeff Patton, User Story Mapping: Discover the Whole Story, Build the Right Product
User Stories have a short turbulent life.
They are born, sit on a backlog for a while, maybe move up and down it, then get chopped into bits, refined, developed and destroyed.
This is why they are not the requirements and not the documentation.
They are not the requirements because they are the promise of a conversation where the ideas we have are explored and refined. These are the requirements.
Some documentation will usually be needed to support the requirements and may be included with the User Story but they will need some other home once done because User Stories die.
For example, we may have one story that implements a basic search. Another comes along and adds a few more rules to the algorithm. A further one comes along, adds some more but also requires our now long running search engine to perform much faster.
If we want to now understand how our search feature works, we will have to assemble a history of user stories and infer what the search should do based on this. These are often conflicting as the results of the basic search may no longer apply when we have added more complexity to the search engine.
Imagine if to understand how your TV worked you had to read through all the notes produced along the way that built it!!
One way to overcome this problem is to produce and maintain alongside the birth, refinement and death of User Stories, an Executable Specification of each feature in the product. It is a specification of the feature as it can include acceptance criteria, descriptions, examples and images of all the screens and designs derived from refinement of user stories for that feature and it is executable in that if these examples are written in a Domain Specific Language (DSL) like Gherkin, then can be executed as automated tests upon our product using a test framework like Cucumber.
As new stories come along and change the behaviour of the feature we focus the discussion on the existing executable specification and make the changes to that. Only using the story as the token of the conversation with some description of what is changing.
The example below shows a feature file for withdrawing cash from an ATM.
The feature file also includes markdown language syntax to allow us to produce a nice readable specification.
# Withdraw Cash Feature: Withdraw Cash ## History Version | Date | Author | Comment | Jira Ref — — — — | — — -| — — — -| — — — — | — — — — 0.1 | 15/01/2018 | Harry Benson | Initial draft | [HA_382](https://jira.dwp.gov.uk/browse/HA-382) ## Table of Contents [TOC] ## Overview As a existing banking customer I want to withdraw cash from my account So that I can go to the pub on a Friday night ## Acceptance Criteria - Can withdraw cash up to £250 a day - Can only withdraw multiples of £5 - Can only withdraw up to my overdraft limit ## Screens ![withdraw_cash](media/15193039850225/withdraw_cash.jpg) ## Links [Bank ATM designs](https://www.pinterest.co.uk/nextmoney/bank-atm-design/) ## Assumptions - Only deal in £5 notes ## Scenarios ### Withdraw cash in £5 increments up to £250 a day and within overdraft limit Scenario Outline: Withdraw cash Given I have “<balance>” in my account And I have “<overdraft>” limit When I “<withdraw>” cash Then I am given “<cash>” And I have “<remaining>” balance Examples: Can withdraw up to £250 a day | balance | overdraft | withdraw | cash | remaining | | £500 | £0 | £250 | £250 | £250 | | £500 | £0 | £255 | £0 | £500 | Examples: Can only with withdraw in multiples of £5 | balance | overdraft | withdraw | cash | remaining | | £500 | £0 | £4 | £0 | £250 | Examples: Can withdraw cash up to overdraft limit | balance | overdraft | withdraw | cash | remaining | | £100 | £250 | £250 | £250 | -£150 | | -£150 | £250 | £250 | £0 | -£150 |
The combination of these two approaches allows us to execute the specification as a test using cucumber and also view the specification using a markdown reader (or export it as a pdf or html page).
The results of running the test are:
And viewing the feature file using a markdown reader:
Now we know what User Stories are, how they are used, and how they feed into providing executable specifications we can move into Part 4 of this series to bring it all together to look at a day in the life of a User Story.