user stories

User Story Requirements Specification Documents

User stories are a very powerful tool for conveying customer value to a development team when used properly. In teams I’ve worked on in the past, stories were merely used as an alternative requirements template to traditional IEEE 830 requirements. Instead of “The system shall…”, everything was rewritten to fit “As an X I want to Y so that Z”, with acceptance tests that often followed this format. When the stories themselves are treated as requirements documents, what actually gets delivered is the developer’s interpretation of the product owner’s interpretation of what the customer wants (this also happens with other forms of requirements documentation that are “tossed over the wall” to development). While the standard “template” of a user story is very effective at conveying the user value of the feature, it leaves a lot of questions about how a user actually accomplishes “Y so they can Z.” Acceptance tests fill in some of the gaps left open by the story, but they don’t quite capture the full essence of the story. We need something to fill in the rest of these gaps to deliver the true desire of the customer. What we need is conversation.

The Goal of a User Story

The problem with many teams is that they don’t know that the real goal of a user story is to evoke conversation. When this goal isn’t met, user stories don’t work. The template and acceptance tests are purposefully terse, and for good reason. In agile software development we value customer collaboration over contract negotiation. We don’t point back to stale documents months down the line and pass blame for incorrectly implemented features or missing functionality. We collaborate. One of our strongest tools in aiding collaboration is the user story. The story and its tests are not comprehensive requirements documents. They are conversation reminders. We write just enough information on the card so we can remember the details of a conversation the next time we look at the story. The details are ultimately captured in the confirmation, or the tests that we write.

What do you do about it?

Having a conversation is so much easier than interpreting a document. I work on a distributed team, so we use an electronic story tracking system instead of good old fashioned index cards. The problem with these systems is that they hold a lot more information than an index card does, and we were making good use of all that extra space. When you have a lot of information written down, people tend to have fewer conversations (which is what we did), and so these “stories” end up being treated like they are written in stone (we were doing that too).

A couple of months ago we had a good discussion about what makes up a user story, and what the real goal of a user story is, and everyone on the team benefited. We now treat the stories as living, breathing things, not stale requirements specification documents. Our stories are very terse now, with a simple description of the problem, and some notes about acceptance criteria. All of the details of a story are now flushed out in conversations among the product owners, testers, and developers. We flush out these details at the start of an iteration, during development, and even during a demonstration. We work together to identify the tests that need to pass in order to call a story complete. We want to collaborate and deliver what’s valuable, not what’s written down on a card.