Chapter 5 - User Stories

A user story is a form of Agile Requirements specification.

A concise, written description of a piece of functionality that will be valuable to a user (or owner) of the software).

They define what will be built into the project. They are formulated in one or two sentences in every day language, understood by both developers and customers/product owners. Anyone can write user stories - typically it's the team members in disalogue with the customer.

The work required to implement them is estimated by the developers, and prioritised by te customer after estimation is carried out.

Benefits of user stories

  • They are quick to write compared to formalised requirements specifications
  • Easier to modify and maintain when requirements change than more formal specifications
  • Enable a quick response to changing requirements (main idea behind agile methods)
  • Encourage face to face communication
  • Minimal investment of time needed until really necessary
  • Allows projects to be broken up into 'sprintable' chunks
  • Gives a unit of work that developers can estimate

How to write user stories

The followign general format is commonly used when writing user stories:

As [role], I can [feature] so that [reason]

Stop focussing on the word 'user', start focussing on roles. Replace the word with 'actor'.

Eg: As an unregistered user, i can register so that I can log in. As a registered user, I can log in, so that I can see my profile page. As a registered user, I can log in, so that I can start a chat conversation.

Sometimes, "so that" can be left off as it can seem redundant. The format does not need to be followed stricktly.

Some alternative formats could be:

  • As a [role], I want [feature] because [reason]
  • As a [role], I want [feature] in order that [reason]
  • As a [role], I can [feature]
  • As a [role], I can [feature] so that [person]

The three C's


Stories are traditionally written on index cards (3" by 5"). The card is annotated with estimates, notes etc.

The following can be captured on the card:

  • Story number
  • Story name - a simple name that can be used to identify it in conversation
  • Story description - "As a ..."
  • Developer's estimate - in story points
  • Conersation notes - can include a sketch of UI, etc
  • Confirmation details (acceptance test details - often written on the reverse side of the card)

They keep the story small, and their descriptions concise. They can be displayed easily for the whole team to look at and monitor. They can be put on a board and moved around easily as the work is completed.


If teams are not co-located, the stories cannot be shared unless in electronic format. Also if teams do not have a permanent workspace of their own it is impractical.


Details of the story are learned during conversations with the customer.


Acceptance tests confirm the story was impemented correctly. The story must be testable to allow developers to know when they are finished. Each story should be accompanied by at least one acceptance test. Given [some context], when [an event occurs], then [some outcome]. They should be written and refined by product owners and developers following conversations.

User Story or Use Cases

There is a difference between user stories and use cases.

The use case is a set of sequences of actions, that yield a result that is of value to an actor.

They are fundamentally different to user stories. The main flow to get the job done, and any alternative flows down to user choice/excpetion. They take more upfront effort, but can guage the difficulty of the task more easily.

The user stories by contrast, gets these individual narratives that collectively build up. Getting what the user really wants and how it can be tested.

For the project, use cases are required.

User roles

It is unusual for there to be only one type of user. The role may refer to a logical user rather than physical. In some cases, the 'user' will appear to be a service or software component.

Users can vary by

  • What they use the software for
  • How they use the software
  • Familiarity with software/computers

Characteristics of good user stories

  • Independent - otherwise they are difficult to prioritise
  • Negotiable - not contracts, just reminders for discussion but the customer is the person who 'knows' exactly what it menas, deveoper strives to understand it clearly
  • Valuable - to the customer, otherwise why implement it?
  • "Estimable"
    • Developers may not know enough about the domain
    • Developers may not know enough about the technology
    • The story is too large to see the 'edges'
  • Brief - stick to the recommended formats
  • Testable - very easy to write un-testable requirements - take care to ensure that the product owner and the developer both agree what a successful outcome will look and act like

A story writing workshop

Includes developers, users, customers, others

  • Brainstorm to generate stories
  • Goal is to write as many stories as possible
  • Some will be implementation ready
  • Others will be epics
  • No prioritisation is done at this point
  • User questionnaries to gain further stories when appropriate
  • Hold user interiews/observe users at work

User stories should ideally be considered as full vertical slices of the system.

Story Estimation

At the start of a project, the initial set of user stories need to be estimated. Estimates are expressed in story points. Some practitioners say not to equate story points to a measure of time, bu tothers say to think of them in terms of 'ideal programming days'. The estimates should be relative as opposed to absolute.

The team should make these estimates together using all expertise available. This can be done using a process called planning poker.

Planning poker

Participants include all of the developers in the team. Each estimator is given a deck of planning cards. Each card has a valid estimation value on it. Some practitioners suggest that these values should follow the Fibonacci like sequence. This speeds up estimation because there are only a few choices. It also avoids a false sense of accurate estimates. Indicated the stories that need to be split up (>20 points)

Steps in planning poker

Step 1
  1. Someone reads out the next user story to be esimated
  2. The product owner answers any questions that the estimators might have about it
  3. ... although these discussions should not go on for too long
  4. The estimates obtained are not considered definite and final, so it is not worthwhile to invest too much time trying to make them completely accurate
  5. It is more important that the relative estimates are good
Step 2
  1. Each estimator privately selects a card representing his/her estimate
  2. Cards are not shown until each person has made a selection
  3. At that time all cards are simultaneously turned over and shown to the rest of the team
Step 3

It is likely that the estimates will not be the same. The high and low estimators for this story should explain their estimates. This should not be about arguing your case though. The exercise is just about learning what everyone was thinking. A low estimator may not see some complexity in a story that the higher estimators can see.

Or alternatively the low estimators might see a straightforward solution to something that the high estimators cannot see.

The discussion should take no more than about 2 minutes before a second round of cards is performed in the same way as before.

Achieving concensus

In many cases this will be enough for the team to come to a consensus on an estimate. However more rounds may be necessary. If the team has the following estimates for a story, 5, 5, 5, ,3, 5, 5; then the low estimator will be asked if they would be OK with a 5.

Remember that the process is not about precision - it is about reasonableness