by Adam Lowe on April 29, 2012

I work on story cards for a lot of projects each year at Hashrocket and also see a lot of backlogs maintained by clients and open source projects. A notable difference that I find between healthy projects and unhealthy projects is the way in which stories are written. I am purposefully leaving out any discussion about managing and grouping stories at a feature set level but will cover that in a future post.

Below is a break down of stories for an example book store that sells pdf's the way I would story card buying a book and the two alternative ways that I see this get broken out the wrong way. Keep in mind that for different projects and project teams story composition will vary to a degree and this is not meant to be a set in stone prescription.

Shopper views book list

  Given a shopper
  When I click library
  Then I am taken to the books list page
  And I see a list of books
  And for each book I see
  - title
  - author
  - isbn number
  - price

Shopper views book show page

  Given a shopper on the book list page
  When I click a book
  Then I am taken to the book show page
  And I see
  - book cover image (104 x 138 pixels)
  - author name
  - isbn number
  - price
  - description

Shopper purchases a book

  Given a shopper on the book show page
  When I click buy book
  Then I am taken to the check out page
  When I fill in my credit card number
  And I fill in my security code number
  And I click check out
  Then my payment is processed
  And I am taken to the payment confirmation page

Shopper views payment confirmation

  Given a shopper that has purchased a book
  And is on the payment confirmation page
  Then I see a message that I successfully purchased the book
  And I see the book
  - title
  - book cover image (74 x 98 pixels)
  - price

Shopper downloads a purchased book

  Given a shopper on the payment confirmation page
  When I click on the book title
  Then a pdf of the book is downloaded to my computer

Users can view a list of books
- title
- author
- isbn

User can view the show page for a book
- cover image (104 x 138 pixels)
- title
- author
- isbn
- description

Users can buy a book
- credit card number
- security code

User views receipt page
- book information, title, price
- book cover image (74 x 98 pixels)

Users can buy a book they downloaded
- pdf

Users can buy books
- list page
- show page (generate cover images)
- users check out (set up payment processing)
-- card and security code
- users can down load a book (set up pdf generation)

In developing software, especially software for someone else stories are more than just a placeholder for conversation. At the point in time when you build the thing they describe they become a social contract to deliver some piece of value. With that in mind it behooves you to be specific in what exactly you are going to deliver. Provide your client with a clear and meaningful set of steps that they can walk through and accept that you provided that value once it is built. This will go a long way towards preventing communication issues and keep you moving forward delivering value to your client rather than resolving communication and perception issues.

1. Each story should describe a single clear interaction and its outcome. Conditional "if" statements or an over abundance of "and" or "when/then" combinations is a smell.
2. Use your client's business language to describe the actors in your stories and avoid ambiguous terms like "users" and "admins" when possible.
3. Your story should provide clear steps that your client can walk through to verify you built the feature they asked for.
4. Title and compose your stories with clear, affirmative statements. "Can" is noise in stories.
5. Your story should describe where you are and where you end up. This will go a long way to preventing bugs related to user's paths through the application.
6. Implementation doesn't belong in your stories. The exception is sometimes stories around things like API's but I will tackle that in another post.
7. There is an implicit acceptance item in every story that the feature delivered matches the design your client previously approved. This also helps you not muddy up your stories trying to describe design elements.