Introduction to Writing User Stories in Agile

The agile manifesto suggests software teams should focus on working software over comprehensive documentation. That lead to the slow erosion of detailed specifications, and the rise of the poem-like snippet just above this paragraph. The example above is from classic story template format. These stories were originally designed to literally tell a story of how a user would use a feature.  User stories in agile help the team understand what problem the code is solving, and specifically, help testers decide what parts of the program they need to focus on. The idea seems simple, but like always digging under the surface will expose some complexity.

This article will take a look at common uses of user stories on agile development teams, how and when they are useful, and some ways to make them more effective

What Does a User Story Look Like?

The most popular way to start with user stories is with a template something like this:

As a <User Role>
I want to <Perform some action>
So that I can <Get some value>

These three lines capture a lot of information. The first line tells the team who will be using the software. That helps the programmer and tester understand the person that will be using this new product. The second line in this template gives information about what the user wants to do. Maybe they want to order a pizza, maybe they want to start a new game of Flappy Birds, or maybe they want to read information off of a pacemaker several states away. The last line of this statement is the ‘why’ part. This explains how the new software will fit into the lives of the person using that product.

Altogether, this story is a value proposition, it is a way someone might have a better day by using software. 

Why User Stories in Agile?

Let's compare this tiny snippet, the user story, to a full-specification approach with a traditional project.

With a traditional project, the team gets all the requirements up-front; the time scale stretches out far into the future. A waterfall project might start with 4 months of requirements gathering, and then have 4 months of writing and revising a specification. After this comes a few months of development and testing. It is difficult, sometimes close to impossible, to make revisions to a requirements document after that 8 months of work regardless of how wrong or out of date (or missing) a line in the document is. User stories were created as a tool for getting on with it in a matter of weeks instead of months.

A requirements document might specify that a page should have fields for first name, last name, social security number, and age. That document might also define exactly where those fields appear on the page down to the pixel, how large they are, and what types of data they should accept or reject. The goal was to remove all ambiguity, to create an exact recipe for a developer to follow. That recipe rarely worked out of course. The product managers creating them often got things wrong, and programmers often misinterpreted the contents no matter how clear someone thought they were. User stories embraced the idea that this level of detail and time wasn't working.

User stories don't focus on those details. Instead, the tell a story of what a user will do with a tiny sliver of the application - leaving the user interface and other elements to the team to decide by conversation. In fact, stories usually don't define much at all about how a piece of software should be implemented. A programmer won't find anything about what text fields and buttons go on a page, how that will tie into a workflow, or what the user experience should be. The small amount of information in those stories is kindling for a conversation. Developers reading them might ask what characters are reasonable for a first name, and what age ranges are acceptable. The testers might ask what happens when a user submits something isn't an age, or doesn't enter a value for age at all. That can happen, and many teams add documents to wherever the story is tracked with detail - but it happens much later, and is recorded so the team can remember the shared agreements they made about the implementation.

What was a several month long process with a rigid result in waterfall operations, becomes a conversation spanning several days and adapting to new information when it is discovered. 

What are the negatives of user stories?

There is at least one major downfall to user stories, in that no one knows exactly what to write on the card to get started. The story template designed above was created to give people a jumping-off point, but the three line story with all the interesting detail stripped out isn't really that much of a story, now is it? The meaning implied in types of users (administrator, bank officer, customer) might not provide much insight to the technical staff. A "Manager" sometimes needs to act as a data entry clerk. The roles overlap and get complicated faster that a team can imagine. Defining what a person might want to do and why in such short terms is asking for trouble. For that matter, many systems only really have one user role, leading to stories that read like "As a user I want to log-in so I can be logged in." Using the format adds more text, but not any real value, to the statement "Login Feature" or "Happy Path Login."

A more powerful approach would be to create an actual story.

Talk about the user for a piece of software:

  • Who are they?
  • What is a normal day for them?
  • What problems are they having now?
  • How will this software solve it?

This is a chance to create deep context around new software. Testers are in some ways encouraged to use a bad testing approach, take each story and turn it into acceptance criteria, when the basic template is used. This can easily be turned into examples like this for a first name:


María-Jose Carreño Quiñones


no value

These examples illustrate long names, simple names, no name entered, and names made of special characters. This is the way of specification by example, and it can be used with the story template format, or with just a brief story-title, like "Login" or "Add Middle Name To Profile." Even the second example, about middle name, could be a story, if the team creates an actual story about the value of the feature -- perhaps passengers with identical names are common on large commercial flights, which can lead to confusion, and this system wants to record the user name so it can pass that and auto-populate the ticket screen.

User stories can be a valuable tool

They allow teams to iterate on requirements, starting with a simple idea that has real value for the customer, then elaborating on that idea through conversation and examples.  At best, they shine a light on the user and help guide development that will solve more problems than it introduces. At worst, what are called "user stories" are really over-vague requirements documents. The problem happens when they go unquestioned, when the team never has a conversation - when the team literally does not know the story the feature is supposed to enable. Try them out and see how user stories enable the team to sketch out high-level plans and move forward iteratively.

Additional Resources