Writing good User Stories

Thu, 20 Feb 2014 00:00:00 +0000

First, it should be noted that not all stories are “User Stories”. For example a developer might be tasked with manually running some script. The Story might simply be “run the fooberry script”.

For everything that effects the UI, use a template:

As a < type of user >
I want < to perform some task >
So that < I can achieve some goal >

Note that it’s all about what the user wants. This isn’t about instructing what change to make to a system. It’s about advising implementers on what the desires of the user are.

Sizing, details, content

Now, everyone says user stories should be “testable”, and “small”, but what does that mean?

Stories should be “Testable”

You’ve heard it before, but its a horrible way of expressing the intent. In general, a story is not directly testable. A Story is only testable through its Acceptance Criteria.

Acceptance Criteria?

Each Story should have a compliment of Acceptance Criteria which cover every interaction, and outcome of the Story. Think of it this way. If you write code that meets every Acceptance Criteria and nothing else your coding work should be done. You should not need to write anything else in order to satisfy the Product Owner. Furthermore, you should be able to write a unit or functional test for each acceptance criteria. If you find your test is testing multiple aspects of the system then your acceptance criteria is too large in scope.

For example: if you’ve added a new page to your app one of the acceptance criteria might be “Administrative users will see a link to the new page in the upper nav. on all pages” This acceptance criteria would pass regardless of where the new link appeared in the “upper nav.” If the Product Owner cares where it appears then the criteria isn’t specific enough. Note that it also specifies what pages it will appear on. Without that you could put it on the “wrong” page and still pass the criteria.

In XP (Extreme Programming) they use a 3"x5" index card to create all their user stories. The story (in template form) goes on the front, and the acceptance criteria go on the back. The rule-of-thumb is that if the acceptance criteria don’t fit on the back of the card, then the story is almost guaranteed to be too big.

Story Sizing

How small is too small? A Story is too small if, by itself, it provides no business value, like this: “As an Administrative User I want to have a link to the new page so that I can navigate to it.” Unless someone’s already created and deployed the new page, it’s a link to nowhere. The next question, of course is how big is too big? I’d say it’s too big if it can still be decomposed into multiple smaller pieces of deliverable business value.

General Tips