Barking Iguana

It's quite a head-shift to start using story-driven development. Often it's hard to work out what a story should contain and who should be involved in writing it. Wouldn't it be nice to have some guidelines to help you get started?

I assume below that you're following Scrum or a Scrum-like development methodology. If you're following another Agile methodology then you should be able to change most of it to fit your situation. If you're following Waterfall, RUP or anything like that then you have my sympathies. I have no idea how well story-driven development will work outside an Agile methodology.

Why write stories?

A Product Owner rarely cares that you've added a button to submit an order unless the code is also there to process the order, take payment and add the order to the database: they care about being able to place an order, not how the ordering system was implemented.

Stories form a complete, deliverable unit of work that can be used to communicate project progress to the business.

Stories make it easier to commit to work for the sprint: the complexity of a feature can be estimated and based on that the Scrum team can tell if they can complete the story in the current sprint.

Stories generate conversations: they help specify the behaviour of a feature so the Scrum team knows what they're aiming for.

Stories make it easier to focus: if a team knows they've committed to delivering a story about placing an order then they're not going to work on adding a user feedback system (or if they do then they can be gently steered back to the goal they committed to during Sprint planning).

When should a story be written?

Since feature requests arrive all the time it's useful to have a regular meeting for writing and estimating stories so I suggest a short meeting at the end of each Sprint to handle the the work that arrived during that Sprint. This meeting is likely to last less than an hour.

At project start-up you'll have more features to estimate than you normally would. Take two or three meetings of between one and two hours to do this.

It's always handy to have more stories than are in the current Sprint as if the team finish their chosen stories early they can choose to accept more work for that Sprint.

Try not to disturb the team too much: writing stories is great, but working software is more important.

Where should stories be written?

There's not really much to this answer: you want to be undisturbed with the Product Owner while you're writing stories. Find a room away from the work area or possibly go to a coffee shop.

Who should write a story?

Short answer: everyone. The Product Owner, Scrum Master and the Scrum Team.

How should a story be written?

The team talks about the product and identifies a specific piece of functionality to be worked on - for example, the ordering system mentioned above. The Product Owner, Scrum Master and Scrum Team then specify a bunch of scenarios that detail the behavior of that functionality: What happens when the store is closed? How about when an invalid credit card number is used? This list doesn't need to be exhaustive, it just needs to be representative of the functionality.

The scenarios and the description of the functionality are captured in a document. This document can take many forms, but the way I write them looks like the below example.

Feature: Place an order
  In order to get goods from our online store
  A shopper
  Should be able to place and pay for an order
  
  Scenario: The store is closed
    Given the store is closed
    And I have three beachballs in my shopping cart
    When I submit my order
    Then the order should be accepted
    And I should see "Your order will be processed when the store opens at 9am"

  Scenario: An invalid credit card number is used
    Given I have three beachballs in my shopping cart
    When I fill in "credit_card_number" with "MONKEY"
    And I press "Pay"
    Then the order should not be accepted
    And I should see "Please enter a valid credit card number"

Now everyone on the team except the Product Owner will estimate the complexity of each story. That is, based on current information, they will assign a point score to the story which shows how complex they think it is compared to other stories. It's good to have a fixed scale here, and it's common that this take a form similar to the Fibonacci sequence. I use ?, 0, 1, 2, 3, 5, 8, 13, 20, 40 and 100 and infinity. A complexity of 0 means the task is trivial. Infinity means that the Scrum Team think they could never complete the story. A ? means the Scrum Team doesn't know: it may be possible to estimate this task after more discussion or after a short, time-boxed development spike. One of the best ways to get the team to estimate complexity is to play planning poker. I have a set of planning poker cards for this.

It's useful to have the Product Owner assign a business value to each story too, although business value is very hard to quantify. I suggest values of 100, 200, 300, 400, 500, 600, 700, 800, 900 or 1000 are used to rank stories to show how important they are compared to each other. The Product Owner should not be swayed by how complex the Scrum Team think the story is: they're rating the value to the business of being able to complete some task regardless of how hard the Scrum Team thinks the task is.

For both complexity and business value there are no in-between values. Don't allow estimates of 25 if it isn't in your scale at the start of the project or you'll spend forever arguing about whether some task is a 24 or a 25. The estimate doesn't need to be exact, it's an estimate.

Business value and story complexity can be changed whenever new information is received so it can be useful to have a brief review of existing unimplemented stories while writing and estimating new ones.

After a story is written it gets added to the product backlog.

What happens to the story after it's added to the product backlog?

During the next Sprint planning meeting the Product Owner, Scrum Master and Scrum Team meet to decide the goal for the upcoming Sprint. This goal will be what the success of the Sprint is evaluated against.

After a goal is set the Scrum Team will discuss the goal and decide which stories that contribute towards the Sprint goal they can commit to delivering during the Sprint based on the complexity of those stories. Stories which deliver high business value should be preferred over those that deliver low business value. The aim is to provide the highest business value possible in each Sprint. There may be some negotiation with the Product Owner here if they decide that they'd prefer some stories implemented instead of others, but the Scrum Team shouldn't be pressured into taking on more complex tasks than they think they can handle.

The amount of complexity that a team can handle during a Sprint should be based on the success of previous Sprints and because each team will estimate stories differently and have different specialties this will vary massively between teams. During the first Sprint the team should pick an arbitrary but sensible number of stories and see how they get on - if they complete all their stories they can always pick more to implement.

How do I know when a feature is complete?

Since a story represents a feature, when the feature is complete you will be able to do exactly what the story says. Try following the story yourself. When you can follow all scenarios in the story then you can consider the feature complete.

If you're using Rails or Ruby you might want to check out my article on story-driven development using Cucumber which shows how to make an automated test out of a story.

What happens if a story doesn't get completed during a Sprint?

Since Scrum focuses on delivering working software, if a story isn't complete then it shouldn't be part of the Sprint Deliverable. If your developers are working in a feature-branch pattern then this is easy to accomplish: just don't merge the incomplete feature into the release branch.

Work that's been done on this feature doesn't necessarily get thrown away. That work can be used to reduce the complexity of a story. If this is done then it's likely that the reduction in complexity of the task will be time-limited: as development continues the cost of keeping the feature branch up-to-date with trunk will begin to weight on the developer.

What happens if a story is too complex for a team to complete in one Sprint?

Stories that contain more complexity than the Scrum Team can handle in one Sprint are called Epic stories. These can't be accepted to work on during a Sprint because they wouldn't get completed during the Sprint: the Sprint Deliverable would show no progress and we should always show progress.

Epics should be discussed with the Product Owner. Frequently they contain descriptions of more than one feature and can be broken down into smaller stories which are deliverable over one Sprint.

It's not unusual to encounter several stories like this during the lifetime of a project.

Any other questions?

Above I've answered the questions that I've asked myself over the past few days. If you have other questions, please ask them in the comments or email me and I'll try to find an answer.

I've been hearing about Story Driven Development (SDD) for a while but I haven't tried it out because I was under the impression that there was a huge amount to learn and setup before I could get going. I'm not sure if that used to be true, but I started using Cucumber yesterday and it was really easy.

Install and configure

You'll need to install a bunch of RubyGems.

sudo gem install nokogiri term-ansicolor treetop diff-lcs hpricot cucumber

Install Cucumber into your Rails app.

ruby script/generate cucumber

Install WebRAT. Unfortuantely this doesn't seem to be available as a RubyGem. If you're using Git then install this as a submodule instead. We're not so I clone the repository then svn add it.

git clone git://github.com/brynary/webrat.git vendor/plugin/webrat

Writing your first story

Stories have three components: a business value, the role of a person that uses the feature and some description of the feature.

In order to [do something with business value]
As [role]
Should [describe the feature]

An example might be the ability to order a pizza from the online ordering system of a pizza delivery company.

Feature: Order Pizza
  In order to get some hot, tasty pizza
  A hungry pizza lover
  Should be able to order pizza

Next we need to define some scenarios. Scenarios are things that can happen during the story. Most pizza places aren't open 24 hours a day so two simple scenarios are (1) the pizza shop is closed, and (2) the pizza shop is open.

  Scenario: The pizza shop is closed
    Given the pizza shop is closed
    And I am on the home page
    And I click "Feed Me!"
    Then I should see "Sorry, the shop is closed"

  Scenario: The pizza shop is open
    Given the pizza shop is open
    And I am on the home page
    And I click "Feed Me!"
    Then I should see "Your pizza will be with you soon"

The above description should go in a file called something like features/order_pizza.feature where it is lovely and version controlled and safe.

So, we now have a story that describes how a feature should behave. How does that get turned into acceptance tests? Well, you could pass these descriptions off to your testing team, or you could turn them into part of your test suite.

Automated tests: better than cake

You might notice that when installing Cucumber you got the directory features/steps. That's where you tell your test suite how to understand your stories. There are already two files here: common_webrat.rb which gives your test suite a few funky things like the ability to click links and env.rb which does pretty much the same stuff as spec/spec_helper.rb except for Cucumber. You can ignore env.rb, but common_webrat.rb will provide a few examples of how to start writing story steps.

Create a new file, order_pizza_steps.rb. This is where you define the steps involved in ordering pizza. It's pretty much just regular expressions which match each line of a scenario to some Ruby code.

Given /the pizza shop is open/ do
  PizzaShop.open = true
end

Given /the pizza shop is closed/ do
  PizzaShop.open = false
end

And /I am on the home page/ do
  visits "/"
end

That's all we need to do. The common WebRAT steps provide the necessary mapping for clicking buttons and checking for feedback.

Running your stories

This is pretty simple: run rake features. You should get some rather pretty coloured output, and if anything has gone wrong Cucumber is pretty good at suggesting ways to fix it.

Found this article useful?

If you enjoyed this article I'd appreciate recommendations at Working with Rails.