Tuesday, January 8, 2013

A Checklist for Effective User Stories

Even though the classic Agile position is that a story is just an starting point for a conversation and thus should only be a sentence or sketch, this only works well for certain kinds of teams and projects - within big corporations, you usually need to do more to document the story for stakeholder review and to retain knowledge within the team. But you don't need to do too much more.

Having a good story pattern or checklist makes it much easier to get the essentials captured without going overboard on documentation. Here are the eight checkpoints I run through when I prepare a story:


1.The story. As a (role), I want (to do or have something ) so that (I get this benefit).
In addition to this statement, you can add one or two short paragraphs giving any necessary background explanation of the problem and goal. This is important to help decide the priority of the story.
2. What is in scope. A list or statement of what everyone agrees will exist when this one story is done. Note, this is a list of what to do, not how to do it. 
3. What is out-of-scope. Give a general statement or list of specific of exclusions. These are the things everyone agrees go beyond the current goal. ( E.g., this story will not calculate depreciation using LIFO method; or, the ability to add comments will be handled in a separate story, etc.)
4. Assumptions. List any assumptions made about existing functionality or data access. Getting assumptions in the open reveals mistakes or misunderstandings that could complicate things.
5. Open questions and issues. List any questions still to be resolved and update them as the answers become available.
6. Design artifacts. Don't go overboard but do include at least one relevant sketch, screenshot, flowchart, design diagram, mapping table, etc. Pictures can say much more than writing.
7. Dependencies and related stories. What else should developers, testers and reviewers know to put this new story in context? What others stories must be complete before this one can go forward?
8. Acceptance tests. Given (the system's starting state), When (this action occurs), Then (the system delivers this result).
Acceptance tests are the BA/product owner's contract with the developer how they, the product owner/BA, will test the story. A BA/product owner cannot fairly reject a story if their test was not included in the acceptance criteria.

1, 2, and 8 are necessary. You can't have a story without them. 6 is also almost always necessary if you're doing anything that has a strong UI component, but sometimes it's OK to add or update this after development starts or after the story is completed. In this way the illustration acts as a guide for tech writers and the support team.

The other checklist items are optional but it's a good idea that any record of the story indicate when something is not applicable. In other words, let readers know there are no open questions and no dependencies.

Remember to keep it short. If you are telling the background story, keep it to one or two short paragraphs and no more than three or four sentences each. If you are listing out points, (e.g., a list of assumptions) no item in the list should run more than one or two sentences (think one-liners).

If you are writing more than that, you may have bitten off a story that is too big or you don’t know enough about the situation to isolate the central objectives. Stop what you are doing, check in with your teammates and SMEs and try again when you have a better handle on the situation.

PS: Later Developments - This is a discussion on LinkedIn about how to write user stories in which I take a troublemaker role: How to Write Good Stories.