Writing Good User Stories

User stories are tool that originated from Extreme Programming and have become the de facto way Agile teams document and collect their requirements.  There is a lot written on user stories (link, link, link), so I am just going to talk about what I consider important in writing good stories since I see a LOT of really bad ones out there today.

For those who do not know, stories are a lightweight artifact that allows us to both capture the business’s needs AND plan the work.  They are typically written on index cards (yes…little 3×5 or 4×6 cards) in the language of the business or customer.  With user stories, we only write enough to capture the user’s needs and no more.  We tend to view stories not as complete specification of the requirements, but as placeholders for later conversations between the developers and the business.

When used properly, a user story’s lack of detail provides us a great deal of utility – we can use the same document to talk about a requirement from a high-level, zoom in on implementation details and jump back out, all in the course of a few sentences.  Then once we are done talking about requirements, we can consider risk, identify dependencies and create a project plan without ever having to put down the index card.  Wow !!  I know of no other requirements artifacts out there allows us such utility.

Over the years people who are really successful with stories have settled on some commonalities found in all stories:

• Role: who, or what, is going to use this feature?
• Feature (or capability): what is the Team going to deliver, or add, after they finished their work?
• Value: why does the business even want this feature?  What impact to the business will it have?
• Acceptance Criteria: how will we know if this feature is done?
• Estimate: how much does the Team think this feature will cost?

IMO, in order for a story to be considered complete it has to have ALL the characteristics described above.  I find that when people have trouble with defining all the characteristics, the stories are not what I call ripe, i.e. they have not been thought through well enough to be usable by the Team.  In addition to these characteristics, stories also should follow the INVEST criteria (this great article by J.B. Rainsberger talks about INVEST as well).

Mike Cohn has written a great book on user stories.  Unfortunately, for all the goodness in the book, folks seem to have focused on the one bit of junk in the book – the user story template.  In his book, Mike offers up a template some teams found helpful with writing stories and from there this template has been the source of so many bad stories that I am not going to give it anymore more ink (or bits).  What I object to about the template is that it causes people to stop thinking as they mechanically fill in role, feature and value and omit acceptance criteria and estimate (presumably because they are missing from the template).  When I see people struggle with stories, it is because they are trying to jam their business into some template that helped some unnamed team  (who probably doesn’t even use this template anymore) five or six years ago and – surprise – it doesn’t fit where they are right now.

There is a thinking process that needs to occur before you write a single story.  The steps I tend to see people completing who are successful writing stories are listed below.  Please keep in mind, while these steps are linear in my post, one can jump back, forward and skip around as it makes sense.  The goal is to have answered these questions by the time you have finished your user story exploration.

1. What are the roles (or users) that will use your system?
2. What are their needs?  How does the product help them accomplish that?
3. What features (or capabilities) do you want to provide these roles?
4. Why are these features valuable to the business?  What sorts of business outcomes can we expect from these features?
5. What are the priorities of these features?  Did we make a promise to deliver some already?
6. How would you know if these features are done?

Finally, people have a tendency to want to write a lot of details on the front of the story card.  I have two suggestions for these people.  First, use smaller cards – really.  User stories are NOT specifications or requirements documents.  They are just index cards capturing the user’s needs and reminders that we have to capture those implementation details later.  If you are trying to cram more and more onto an index card, that might be sign that you may need specs or some type of design documentation in addition to user stories.  Second, the types of details that people are trying to write down are actually acceptance criteria.  By pushing those details into the test cases, we keep the story in the language of the business and retain the focus on the feature and value your Team is providing.