Articles & Tutorials

The articles and tutorials here are provided free of charge, and are fueled by caffeine.

How to write meaningful User Stories

I’ve seen a lot of projects fail when by all accounts, they shouldn’t have. The reason for this nearly every time, was that the requirements gathering stage of a project was done poorly, or sometimes not at all.  Sometimes this is driven by budget or deadline constraints, and sometimes it’s because the people responsible are just unaware of how to go about gathering requirements in a structured manner, and if you’re one of those people, or know one of those people, then please read on.

Requirements exist to make sure that what you think you are building, is the same as what the client or stakeholder thinks you are building.

Requirements serve many purposes, but when you strip them down to their core, requirements exist to make sure that what you think you are building, is the same as what the client or stakeholder thinks you are building.  Because of this, they should be as easy to read and understand as possible, which things like functional specification documents usually aren’t.

There are many types of people that think many different ways.  Designers are usually visual thinkers, and Developers are usually logical thinkers.  Clients could be either.  To help as many different types of people understand your documents, I recommend using at least 2 different techniques to form your final document:

  1. User Stories
  2. Wireframes

This article will cover what a user story is, how to write one, and how they can help steer your project towards a successful outcome.  Wireframes will be covered in a later article.

What is a User Story?

A user story describes a small piece of system functionality, in a simple and easy to read sentence.  A well written user story will describe what the desired functionality is, who it is for, and why it is useful. 

There are 3 parts to a fully fleshed out user story.  If you like marketing-speak, then you can call them the “3 C’s”:

  • The Card
  • The Conversation
  • The Confirmation

The Card

A typical user story follows this template:

“As a [user], I want [function], so that [value]”

Having such an easy template to follow allows anyone involved with the project to help write them, from sales, to designers, developers and testers, all the way through to clients or users. 

We refer to this as “The Card” because often they are written on 3x5 bits of plain card, usually to give a physical constraint which limits the possible length of the story. 

Here’s a few hypothetical examples I’ve written for YouTube.  I’ve defined a “Creator” as someone who contributes videos to the site, and “User” as someone who just watches them:

As a Creator, I want to upload a video so that any users can view it.
As a User, I want to search by keyword to find videos that are relevant to me.

As you can see, with such a small statement we gather a lot of useful information that we may not have been provided otherwise, including who we’re doing this for, and what value it will bring.  But it’s not the full picture, or enough information to start building things yet.  This is where the conversation comes in.

The Conversation

Think of the conversation as an open dialogue between everyone working on the project, and the client.  Anyone can raise questions, ask for things to be clarified, and the answers can be recorded down as bullet points for later reference.  It is also a stage where you can reevaluate your user story, and possibly split it into multiple stories if required.

For example, we discuss the creator upload user story, and decide that there are actually multiple things that can happen, so we split them, and expand on them:

As a Creator, I want to upload a video from my local machine so that any users can view it.

  • The “Upload” button will be a persistent item on every page of the site.
  • Videos must not be larger than 100MB, or more than 10 minutes long.
  • File formats can include .flv, .mov, .mp4, .avi, and .mpg.
  • Upload progress will be shown in real time.

As a Creator, I want to edit the video’s metadata while a video is uploading, to save myself time.

  • Editable fields include Video Name, description, tags, and privacy settings.
  • Once saved, the user will be taken to their video’s dedicated page.

Once you write a few of these and get into the swing of it, you’ll find you’re getting a lot of data written down very quickly. Because of this, it’s important to organise your user stories in a manageable way.  I like to group them by interface, and present them next to a wireframe showing the intended functionality.

The Confirmation

The confirmation is basically just a test case.  If you’re not familiar with test plans and test cases, think of a test case as a series of steps that a user must do to achieve the User Story.  A test plan is a collection of test cases.  With full coverage of your system in your test plans, you can easily test every core piece of functionality and tick them off as you go through them.

A test case for our YouTube example might look like this:

As a Creator, I want to upload a video from my local machine so that any users can view it.

  1. Click the “Upload” button.
  2. Specify a video file to upload.
    1. Check that .flv, .mov, .mp4, .avi, and .mpg extensions are supported.
    2. Check that other filetypes aren’t able to be uploaded.
    3. Check that files larger than 100MB results in an error.
    4. Check that movies longer than 10 mins result in an error.
  3. Click “Upload Video”.
  4. Check that progress is displayed in real time.

INVEST in your user stories

In most places you see user stories being discussed, you may hear the acronym INVEST being thrown around.

It stands for all the things a good user story should be:

  1. Independent
  2. Negotiable
  3. Valuable
  4. Estimable
  5. Small
  6. Testable

Conclusion

It’s only with practice and real world usage of these techniques that you’ll find how useful they really are.  If you’re at a company thats stuck in a “waterfall” development mentality, you could try using this information to pitch your boss a more effective method of requirements gathering.  If you’re a freelancer, try it out on your next project and see how you go. 

I’m interested to hear comments and feedback from any of you that have used well written user stories in your projects and how you found the experience.

6 Comments

  1. Picture of Ryan Cole
    Ryan Cole says:

    Hi Steve,

    This is a really great breakdown of a useful technique. I’ll be integrating this process into my Web Authoring class next semester. I already do some card sorting to show them ways of creating an intuitive structure, but this will really help them to connect the user personae and goals with actual actions and design considerations on their sites.
    I’ll post your blog on the class website. :)

    Thanks tons!

  2. Picture of Steve Dennis
    Steve Dennis says:

    Thanks Ryan :)  Much appreciated.

  3. Picture of Anis
    Anis says:

    Great article!!
    For adding additional information with a card, I’ve used Acceptance Criteria. But didn’t know about this “conversation” and “confirmation” format.

    Thanks Steve

  4. Picture of John Thornborrow
    John Thornborrow says:

    Great article. :)

    We’ve found that it can highlight the value better, by placing it (the value statement) first. So “As a [role], I want [feature/function], so that [value]” becomes “So that [value], as a [role], I want [feature/function]”

    An example:

    So that anyone can view my videos, as a Creator, I want to upload videos from my local machine.

    This helps keep the value in the Developer’s mind. It also makes it easier/quicker to confirm which story a developer is referring to :) We also use “In order to” instead of “So that” depending on which phrase fits :)

  5. Picture of Steve Dennis
    Steve Dennis says:

    Cheers for the tips John :)  I’m not sure the second example reads as well as a sentence (and possibly muddies the intention somewhat?), but at the end of the day anything that works to get everyone on the same page is definitely the right way to go!  “In order to” is a good addition though. Thanks!

  6. Picture of Jack
    Jack says:

    Hi, the User stories are related only to functional requirements?? or are extended to non functional requirements too?

Commenting is not available in this weblog entry.