Writing the story of an application
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.
The Good (Interaction Driven Stories)
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.
Some Basic Guidelines
- 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.
- Use your client's business language to describe the actors in your stories and avoid ambiguous terms like "users" and "admins" when possible.
- Your story should provide clear steps that your client can walk through to verify you built the feature they asked for.
- Title and compose your stories with clear, affirmative statements. "Can" is noise in stories.
- 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.
- 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.
- 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.