A lot of folks who dive into the world of Agile (be it Scrum or XP) will need to learn how to write stories. Stories are an expression of a feature which provides value. They typically take the format of “As a {user-role} I need/want to {some functionality} so that {value}.” I coach people to use what I call the 3Ws: Who is the user, what is it they want to do, and why do they want to do that? Any well written story should be able to answer those three questions.
The following is an example story that isn’t written well:
“As a manager I want documentation produced so that the software can be understood by people.”
Who’s the user here, the manager – really? It doesn’t sound like he’s the one using the documentation, “people” are (whomever that is). ”Documentation produced” also is a task – not an expression of functionality. The value statement is also dubious “so that software can be understood,” but why is that valuable for “the people?” Reading this story leaves you with too many unanswered questions and is overly vague. You can quickly see this story fails to answer our 3Ws.
Instead, a better approach, is to make documentation part of the done criteria (or acceptance) of the actual feature the story should be addressing. Remember with stories we want to end with a demonstrable unit of work. If the feature was to add the ability to send e-mail after someone comments on a blog post, for example, you might have something like this:
“As a user who’s commented on a blog post I want to receive a notification anytime additional comments are added so that I keep up with the conversation.”
This story is much better. We know that we’re talking about people who have posted a comment on a blog post. We know that they want to receive a notification anytime new comments are added. They want this because it helps them keep up with the conversation. Anyone could read this story and understand what needs to happen. What’s even better is it doesn’t imply implementation. It doesn’t say I should receive an SMS message, and e-mail or a letter in the mail. Those details will be discussed when this story is planned.
In order to complete this work the whole vertical slice has to be addressed: code business logic, design e-mail template/layout, test feature, write documentation. There isn’t a need to have a separate story for this — I’d advise against it, because your feature really isn’t done if documentation is a requirement. When you finish a feature you want it to be done, done.
Bad Smells
- Story not addressing a vertical slice typically have “developer” or “manager” as the user-role.
- Story doesn’t express business value or functionality, but instead expresses a task.
- Story has dependencies on other stories being done first.
- Story talks about implementation.
