Story Time

Let me tell you a story about stories.

I’ve often been asked what information should be put inside a user story, or what kind of template I use for a user story on a project. In order to provide a useful answer to this question, we must look back and see where user stories came from.


In the beginning, there were requirements documents. These documents were crafted by Business Analysts, signed off by The Business and then thrown over the Great Wall to the Developers who would then build exactly what the requirements document specified. Just in case something was wrong, the keepers of Quality, known as Testers would pass their critical eye over what the developers had built.

Finally the software would be passed back to The Business. Having met all of their requirements, the The Business would, of course, be extremely pleased and happy with the result of this year or so of work.

Except it didn’t work that way. What came out the other end didn’t make the people using the software happy, even if it did meet the requirements.

You have likely heard people involved with building the project say something like this:

  • “We needed to know more detail up front.”
  • “The analysis wasn’t complete.”
  • “There were missed requirements.”
  • “The Business signed off the requirements.”
  • “That was out of scope of the project.”

The result was more time spent writing even larger requirements documents. With very similar results at the end.


The realisation started to spread among the software community that specifying what software should do is hard. Software is a fairly abstract construct that can do a lot of things not possible in any other way. Trying to think about exactly how this construct should behave without seeing it functioning before us was proving impossible. Even with practice, software project after software project fell into the same trap.

Also, due to the walled nature of teams, in many cases the goal of a requirements document was simply to have a good requirements document.

That might sound great, I mean why wouldn’t you want to write a good requirements document? It would have use cases, fancy wireframes, non-functional requirements. They were things of beauty (to a business analyst anyway). Unfortunately the goal of a software project is to have working software that does the thing the people using it want it to do. A requirements document in and of itself doesn’t really have any value.


A different approach to documenting what software should do started to emerge. What if, instead of trying to document in exhaustive detail exactly how the software should behave, we wrote down a high level goal that the person using the system wanted to achieve? Then instead of just going off and building it, that person was involved in a conversation about how they envisioned it working.

Then, what if we developed a rough, barely working version of the software that could achieve that goal and get the person to use it?

What if we replaced walls with conversations? What if we replaced thousands of words prone to misinterpretation, with diagrams, workshops and shared understanding? What if all the people involved in building the software understood exactly what the people using the software wanted?

So became agile unto the world.

User stories are one small piece of this new way of working.


Working software is the output of a system. Not a computer system, but an organisational system that contains actions, events, feedback loops and actors. Take a look at this book to get an idea about systems thinking.

It’s an important concept to grasp in understanding the way many things happen. More specifically in this case, it’s important for us to understand that a user story, and what a user story looks like and information it contains, cannot be looked at in isolation. The user story is one part of the system that produces working software. What a useful user story looks like depends greatly on what your system for producing software looks like.

The original user story format of As a xxx I want to yyy so that zzz existed to help support the ideals of the agile manifesto, and within that context it works very well. Outside of an environment that has embraced the ideals of agile, this format for a user story may not be useful.

Knowing what will be useful information or a useful template for a user story for a team, without knowing how that team works is nigh on impossible. What can be useful, is having an idea about what ingredients are necessary as input for successfully building useful software. Then seeing which of these ingredients are missing or unclear in the system that’s producing software can guide you toward what needs to be recorded inside your user stories.


  • Who
    • Who wants this work done?
    • This could be an external user that wants a feature or an internal team that needs access to a certain API.
    • May also be seen as: actorowneruser.
  • What
    • What are the outcomes expected from completing this story?
    • May also be seen as: requirements or objectives.
  • Why
    • Why does this story exist?
    • Which events led to needing this piece of work done?
    • May also be seen as: context or background.
  • When
    • When is the story considered finished?
    • May also be seen as: testsacceptance criteria.
  • How
    • How will the outcomes be met?
    • May also be seen as: technical implementation.


Let’s take a look at how these building blocks map onto the commonly used user story format:

As a xxx I want to yyy so that zzz

This seemingly simple statement covers most of the information outlined above into a very compact format, and gives some insight as to why this style rose to prominence.

  • Who – As a xxx

  • What – I want to yyy

  • Why – so that zzz

When and how are all that’s missing here.

Acceptance criteria can be used for adding when information. I usually leave the how up to developers to figure out and decide where to record.


Not everyone likes the classic formatting of user stories, and while they can be great for front end work when the As a statement is easy to write, when you start working on back end services you might start to see a lot of As a system popping up.

I’ve also worked on a team where the developers re-wrote each story on the back of the cards. The reason for this being ‘I want to know what I have to build.’ The project in question was a digital payments compliance project. In this case, the who part of the user story was not adding much value, and just cluttering up card space.

We changed the physical cards to just contain a simple statement of what. In our story tracking tool we recorded the following:



After a couple of iterations, Acceptance criteria was also added.

For that team and project, we found the combination of physical cards on the wall with a simple how statement and virtual cards with more information very effective.


Just like everything agile, there is no one formula that works for every team or project. Thinking carefully about what information is important for your project and modifying your style to suit will always yield better results than blindly following any kind of template.