How should user stories be written?

As my old friend Charles Bair used to say, that’s a two-part question. “How?” and “should user stories be written?” The answer to the second question is “No, not really.”

This notion comes up owing to preparation for a panel at Agile 2008, in which I have decided not to participate for personal reasons. But I’d like to share my concerns and thoughts.

What is a User Story?

A User Story is a piece of system functionality, understood by the Customer / Product Owner, representing an increment of business value, to be implemented by the team.

A User Story is not a requirements document. It is not a written communication between requirements giver and requirements implementor. A User Story is just “a thing to do.”

How is a User Story Devised?

Well, in principle a user story can be devised in any old way. The requirements giver “thinks them up”. However, there are valuable principles to consider.

The “As a … I want … so that …” notion reminds us that we need to consider all the users of our product, that we need to consider what they want to accomplish, and that we need to turn that into a feature that they want. These are all good things for a requirements creator to think about … and they are all valuable to communicate to the developers, to aid their understanding.

The “INVEST” notion reminds us that stories should ideally be Independent, Negotiable, Valuable, Estimatable, Small, and Testable. All good notions that should be considered when deciding what to ask for.

So these ideas are very important during the time when we are trying to think of stories. At least some aspects of them are well worth communicating across the whole team.

How is a user story communicated?

I’ve written on this before, in my article on Card, Conversation, Confirmation. The fundamental notion for our purpose here is that a story is communicated to the team by conversation. The communication is not a written document supported by Q&A. It is an explicit conversation between product owner and developers.

The conversation ideally ends with a clear statement of the acceptance criteria for the story, answering the question “How will you know that we have done what you’re asking?” The answer comes, again ideally, in the form of one or more executable tests which, when they work, show that the story is done.

How is a story tracked?

A story goes through a number of state transitions in its lifetime. It starts as a gleam in the eye of the product owner. It becomes something the product owner really wants. It becomes something that the product owner decides to schedule. It gets scheduled into an iteration. It is coded. It is tested. It is finally deemed to be done. Through all these states, we want not to lose the story, and usually we want to know what state it is in, especially as it goes through those final ones. How might this tracking be accomplished?

One really great way is to create a card representing the story, and post it on a wall chart showing the story’s current state. In one of his excellent articles, Jim Shore provides this picture of story cards on a wall:

Story cards on a wall are simple, public, easy to maintain, highly participative, and communicate very clearly. Highly recommended. What should the cards say on them? Anything at all that reminds everyone of what the story means. The card could say “Overtime Pay”, even if the original thinking was “As a manager of hourly-paid employees, I want them to be paid overtime in accord with the law and our policies, so that they will be properly compensated and we will be rightly seen as a just and friendly company.” We discussed all that stuff in the Conversation. We only need to quote enough of that to remind ourselves what we were talking about.

And remember: the card is backed up by an executable test that is quite probably under version control in the software repository.

That said, some teams, rightly or wrongly, want to do more. Perhaps they want to have some kind of database of story definitions, or to communicate stories across time and space. Personally, I’d push back against those notions fairly hard, but there certainly are cases where that’s what you should do.

When you do, however, you have just committed yourself to a different, heavier form of user story. The card is just a token for the story, used to mark its progression through the process. This heavier thing now begins to serve as a permanent archival document, part of some formal representation of the project. It is certainly OK to do this, even if by some standards it is wasteful.

A formally written story is an option!

By Agile standards, turning the story into a document is an option, not a standard and necessary part of doing user stories.If we are going to do it, we should strive to write the minimum amount that will serve the need in hand, which may be nothing more than to tell some remote team members what is going on. For some teams – few teams, I believe – we have additional needs for archival properties, or distance-communication properties, that require us to do more. We should do that … albeit only reluctantly.

Bottom Line

The story is a user-understood bit of requirements that the team is going to implement.

The best way to communicate to the team what is needed is to talk with them. The best way to be sure we have a mutual understanding is to define a test. Some kind of document might be provided as backup or detail on the conversation. That document should not be carrying most of the weight of the story: it is the job of the conversation, and the confirmation, to do that.

The “As a … I want … so that” and “INVEST” notions are quite important during consideration of what stories we need, and may be important during the communication of the story to the team. That doesn’t mean anything should be written down in this format … nor does it mean we can’t write things down that way if we want to. We’re allowed to do that. It’s not required.

Thus we see that a user story is a thing that needs doing, that must be effectively communicated and tested. We see that a user story card or a user story tool entry might be a written sort of thing. But the writing is not the most important part. Quite likely it is the least important part, far behind the thinking, the communicating, and the testing.