Friday, November 03, 2006

Story Card Format

A friend of mine recently wrote:
Realizing that TW has NDA's to honor, is there anyway you could paraphrase a few User Stories for me so I can see good examples of what they should have? I realize they need only be 2-3 sentences, but since I've no experience with them at all (other than use cases) I don't know what the ideal story should be like. As in, what level of detail are they, verbage wise. Does the customer actually write them on the cards themselves while the developer is nearby to answer any questions?
Below is my response, that I thought might be useful to those adopting Agile.
At ThoughtWorks we generally use a form such as:
As a script author
I would like to save the script language to the database
so that it can be executed and altered in the future.
The underlined words are the 'template'. I've briefly written in the past about why I'm not a huge fan of the template; however, we have had success with it.

At the end of the day a story is a placeholder for a conversation; therefore, use whatever template you can create that will encourage the conversation.


  1. Anonymous1:19 PM

    I usually recommend that stories contain acceptance criteria on a Given/When/Then (GWT) form:

    Given (initial context)
    When (some event or action)
    Then (some observable outcome)


    Given I am not logged in
    When I try to go to the "Add Script" screen
    Then I'm told to log in

    Given I am logged in
    AND I'm on the "Add Script" screen
    When I forget to attach a file
    AND confirm that I'm adding a script
    Then I'm told to select a script

    Given I am logged in
    AND I'm on the "Add Script" screen
    When I attach a file
    AND confirm that I'm adding a script
    Then I'm told that the script is successfully stored

    Why acceptance criteria? Because it makes it easier for developers to know when they're done. And the GWT format is fairly easy to translate to functional tests (FIT, Watir, Selenium, RSpec).

    And yes, this GWT stuff is part of the higher levels of the BDD philosophy.


  2. Anonymous2:56 PM

    I'm not a massive fan of the as a/I want to/so that format either, although as you say it does have its benefits. It's heavily recommended in BT (where I work), to such an extent that most people who've heard of user stories would swear blind that if a card – or a StarTeam artifact :-( – doesn't follow that pattern, it's not a real user story.

    Personally, I tend to favour a simple description, which is just enough that everyone remembers what the story is about, with maybe some extra notes on the back. That way you can write it in marker pen, and read the cards on the wall from across the room.

    Because our customer isn't co-located, we also copy the story to a wiki, where we may expand a bit on the details, and where the acceptance criteria are recorded when the story makes it into an iteration.

    Keeping stories brief like that relies on everyone having a good understanding of the underlying detail – the customer to know the business benefit to allow prioritisation, and the developers to have an idea of the likely technical solution for estimation. It won't work for everyone, and as you conclude the important thing is to find what works well for your particular team.

  3. Anonymous7:24 PM

    Aslak: Thanks for the note. I just got a demo of BDD from Dan North at the UK AwayDay. It looks like really good stuff. I considered adding it to this post; however, I didn't want to put up any incorrect information. I'm glad someone in the know added the correct info.

  4. Given/When/Then makes User Stories read a little like Use Cases, which also easily translate into functional/acceptance tests.

    Given can map to preconditions.
    When can map to triggers
    Then can map to postconditions.
    There probably are other ways to do the mapping as well.

    That said, I do not necessarily push for Use Cases over Given/When/Then. That was just an observation.

    We use the Given/When/Then format on our team. However, I personally have problems easily reading stories and quickly making sense of them when they are written in that format. At least, as Aslak pointed, they easily translate into functional tests though.

    I like Jay's format though and think it complements the Given/When/Then format in some respects.

  5. Anonymous10:24 AM

    Andy: At Dan North's presentation he used the As/I/So format on the front of the card and used the Given/When/Then format on the back, for acceptance criteria.

    As you've already noted, they do seem to compliment each other well.

    Again, I haven't done this in practice though.

  6. Anonymous7:56 PM

    GWT is great for getting a team off the ground writing stories. It is formulaic enough to be easy to follow and ensure the right level of detail/vagueness is used.

    Once story writers are comfortable, then they should evolve their own style that fits their team's needs.

    BTW, I picked up the GWT after seeing some of Aslak's stories (thanks Aslak!) and it is now my recommended format for new clients


Note: Only a member of this blog may post a comment.