User Stories Writing

The Real Story About User Stories

Back in late 90’s Kent Beck came with the idea of stories as a way to solve one of the biggest problem in software development.

The persistence to use documents to describe precisely  what we want, a.k.a “requirements”.

The problem with documents, is that different people, understand different things when reading the same document! If in later phase sth is wrong during the development phase it’s very common to hear that it was due to “bad” requirements(there were not clear, we thought that sth else is required, we misunderstood them e.t.c, you could find a lot of excuses!) There is also another problem with requirement documents. In most of the cases do not describe why we need to implement sth! We understand that, when we have already delivered our software and people start using it!

The solution that Kent Beck came up was to use stories, (a.k.a user stories) to describe why we need sth from the user perspective. The idea is to stop writing detailed documents and start collaborating and telling stories about they way these stories are supposed to be used.

Talk about the problem you are trying to solve, why it is important from user perspective and try to build a shared understanding!

The 3C’s “Card, Conversation, Confirmation”

Ron Jeffries in the book Extreme Programming Installed, described the process related to user stories writing and he suggested to follow the 3C’s approach (Card, Conversation, Confirmation).

Screen Shot 2015-07-24 at 12.14.10 PM


In cards you write down all these things a user will do with the specific product you are thinking to build. Every card should describe a specific behavior and a benefit for the user. Using index cards could help you put them on a table, change their order, prioritize them, organize them into a structure that might help you see the big picture. It is obvious that the card is not large enough to include all these details you are thinking about the specific story. And this is just fine!  It is common said that “if you can’t fit everything in the card, take a smaller one”! Cards are not supposed to contain all the information. It just describes why you are building this story for the user and what will be the benefit!

How to write a story card and what you should write on them?

People from Connextra that were using the concept of stories in their XP development, came with a simple card template. The template goes like this:

As [type of user]

i want to [do something]

so that i can [get some benefit]

This template has been used to describe in a few words, WHO will make use of the specific story, WHAT specific this user would like to do with that story, and WHY this story is needed from user perspective. Actually this story card is the trigger for further conversations and discussion around the who, what and why.


Avoid writing stories form your own perspective (e.g as a Product Owner, as a Development team). Try always to write stories from the “people” that will actually benefit of using that story. If a story is not written in that format, it doesn’t mean that it’s not a story! However it’s important to try first and make good use of this template, since it will help you see your product through the user perspective and will help you initiate really useful conversations. As an alternative to this template you can use the one written below:

In order to [get some benefit] i want [to do something]

Screen Shot 2015-07-24 at 12.14.20 PM

Even if there is no much room to write a lot in an index card, there are a few things that you need to consider:

  • a good title, just enough to be able for other people to understand it. if not well understood be open in comments and re-write it
  • a short description that covers who is the story user, what the user will do with that story and why the user need that story, the benefits will gain
  • an estimation of the story (in points if you are using story points, a size if you are using for example t-shirt sized stories, or any other kind of estimation)
  • relations with other stories if the specific story is part of a group of stories that fulfill a wider need
  • story status, for example if it is ready to be developed in upcoming sprints, if it is in progress, done e.t.c
  • a story number or ID that might be needed for a tracking system and will be used to find a story (if this ID tells more than the’s a good indication that you need to improve your title!)
  • dates related to start working on this story till is it finished. it will be useful to get some measurements out of this like cycle time, e2e time, delivery time e.t.c



Conversation is actually where the details related to solution and the problem or needs that are described in story cards are discussed aiming to create a shared understanding. This is happening prior any document or artifact creation and it’s the place where questions, suggestions, ideas from people with diverse background that participate in story conversations are raised and discussed with a common goal:

Work together to understand the problems or the needs and eventually agree on what should be implemented to meet user needs or solve in the best way the known problems. Try to build a shared understanding!

If it’s important for your context to have sth written on a document, you can log the outcome of your discussions during the conversations.


Create charts, whiteboard drawings, take photos and store them in your repositories. As participant of the conversation you will be amazed how much details you will remember when you will need them. It’s like taking holiday pictures, you’ll have a great story to tell, when you see that pictures!  Remember to keep the group of people discussing the stories small. More than 7 people might impact the quality of the conversation impact. These people will be able to describe later on details to the rest of their team members. Who could participate? I could say, everyone that could positively impact the quality of conversations! Talk about the who, what and why. Talk about how you will develop it and talk about how long it will take! Talk about of different solutions, talk about assumptions and raise all of your questions!


So, you have the cards, you have discussed and achieved a shared understanding, but eventually you need to build the relevant software! Ask yourself

How are you going to check, how you will know that you have done what you are talking about?

How are you going to demonstrate that you have developed a working piece of software that meet the user needs?

This is the confirmation phase where all these discussion are taking place! (a.k.a acceptance criteria or acceptance tests). The acceptance tests/criteria are statements that describe which should be the expected outcome as a result of a specific action triggered by the user. Identifying acceptance tests is a collaborative activity. Don’t expect that the Product Owner is the sole responsible to create them. Everyone that participate in such discussions should think of acceptance tests based on experience, knowledge, expertise, background.

tipsStart by brainstorming on various scenarios, positive or negative ones, scenarios that might prevent bugs, try to discuss any possible assumptions that if not discussed might impact future development. A good way to keep that information is to create a mindmap and later on add the details. As soon as you have the mindmap ready filter those that are really important to meet the user needs.

How to write acceptance tests?

A common used format developed by Dan North and Chriss Matts as part of Behavior Driven Development is the GivenWhenThen style as described below:

Given [some initial conditions] when [an action] then [a result]

The given part describes the preconditions to your test/scenario. The state of the software prior triggered by a specific action or the beginning of a specific behavior

The when describes the specific behavior you would like to begin

The then describes the expected changes you would like to observe based on your specified scenario

Screen Shot 2015-07-24 at 12.15.04 PM
INVEST on user stories writing

Bill Wake suggested the INVEST mnemonic as a reminder of those characteristics that if followed could improve the quality of the user stories. This acronym stands for the words as depicted in the image below


Independent: While sometimes is difficult, user stories should be as independent as possible since any dependencies might make difficult the prioritization and might impede the development. If for some reason it’s impossible to remove dependencies it might be a good idea to combine these stories or mention these “healthy” dependencies in the story card (check relations field). You should always strive in creating a valuable piece of software and if for that reason it is required to create first a few less valuable stories prior a valuable one, then do so!

Negotiable: As said in 3C’s story cards is just the trigger for the conversation part where actually the reason to create that story, the benefits for the user and the way the story will be checked if the expected value is gained are discussed. So a story is not a contract, and for that reason is negotiable and could be discarded, split, combined, updated and enhanced with notes, tests, details during the conversation among all relevant people (development team, PdOs, SME, customers e.t.c). The main purpose of all these negotiations is to create something valuable for the user!

Valuable: A story, if implemented should return back some value! The benefits of the user story as said should be clear defined in the story card and should be the outcome of the conversation around this story. It doesn’t mean that the value should be always returned to the end customer but it might be cases that specific stories return significant “internal” value. To make things simpler, the value should benefit the story user as you have described in the card!

Estimable: Stories need to be able to be estimated or sized so it could be possible to prioritize them properly!  Estimates are done using various techniques (refer to this post on estimation) and in most of the cases stories are estimated in points or t-shirt sizes. Estimates could help you get a view of what need to be implemented first. Highly estimated stories doesn’t mean high value to the user. So based on estimates and the value might return to the user you can make the relevant trade-off aiming always to maximize the outcome to your customers. Estimates could help you get a view of how long it will take to deliver a valuable piece of software to your customer and for that reason estimated are important as well (refer to this post on product planning)! Prerequisite to estimate stories is first to understand them. If it’s not possible to estimated because you don’t understand the story then this is a good indication to do some research (a.k.a spike) so to gain more information and get a better view of the specific story. You can even invite SMEs in the discussions that could help you to better understand the story and estimate it. If you still have difficulties in estimating, maybe this is a good indication to split the story!

Small: Normally stories should be a few days work for a few people within the development team, so good stories tend to be small. Smaller stories are easier to be estimated and easier to understand. But how small should be? Well, depends on your iteration size! The main idea is to fit within your iteration and ensure that you will get a feedback if the story returns the expected benefits as soon as possible and within your iteration! Keep in mind that every story should include all the work that is required to meet your “done” criteria!

Testable: Stories should be testable which means that during story conversation and confirmation acceptance tests should be written. This approach could be beneficial since discussions around quality will occur quite early and could help to employ Test Driven Development.

When to split your stories

Think of stories as a multi layer burger, as the one in the image below. When you bite it you want to taste or get the essence of the whole burger! This is how you should consider your stories, a multi-layer burger that when you slice it you get sth from all layers! Making each slice valuable to the user is what you should aim for and it is close to XP “pay-as-you-go” attitude!

Screen Shot 2015-07-24 at 12.15.23 PM

Splitting stories is a skill and like all skills could be learned. A few ways to split stories are listed below.

Screen Shot 2015-10-08 at 21.00.40

Decision Trees: For complex stories it s common to have more than one decision trees related to the logic you can follow to implement a specific part of a functionality. Each branch you might decide to implement could be an indication for creating a separate user story.

Workflow: If for a specific story there are various steps you need to follow, each workflow step could be a separately story. In such cases the final value to the end user might not be possible until all the previous steps are implemented but you might have some value to the emerged story users.

Acceptance Criteria: The acceptance criteria or tests could be one way to split the user stories. Acceptance criteria that verify the main functionality or the positive scenarios could be one story whereas some negative scenarios, or special cases could be gathered and create an additional story.

None, One, Many: Think of what will happen if you just implement a basic set up with no users in your system or interactions. Think of what will happen if you have just a simple interaction or think of what will happen if you have multiple users or interactions. All these different scenarios could help you create different stories, from basic setup, simple interaction and scalability.

External Quality: If you are still having a complex and large story and you cannot find any other ways to make it simpler or slice it in smaller chunks of code then try to split the story based on the external quality you give to end user. It doesn’t mean that you should compromise code quality but you can follow a similar approach as the Kano Model. To make it simpler, split the story in must have value, nice to have and keep for last any delighters!

Spikes: Use short time boxed spikes as investigation stories to gather more info and knowledge that will help you to discuss and split complex stories (or even when you are not in position to write stories!)

Richard Lawrence has written some great posts on that subject that worth to study!

While sometimes is important to split stories it is also important to know when not to split stories. Don’t split stories to cover just one layer (refer to burger!) and don’t split stories per activity like development and test!

Story writing workflow


here are a few steps you can follow as a general guidance in story writing. 1. prepare the story card with a short description and following your favorite template  2. discuss who will benefit from the story and make sure that you have answers on who, what and why 3. brainstorm on acceptance test while trying to answer how you will check if you have done what the card is saying, and how to demonstrate what you have implemented 4. create a mind map 5. filter those acceptance test from the map that are really important for your story 6. write them following the GivenWhenThen format 7. discuss if there is need to split the story 8. do you have answers on the main initial questions? (how to know if you have done, how to demonstrate). In all discussions consider each of any INVEST criteria!

Learning Path


User Story Mapping

User Stories Applied

Posts & Articles

Essential XP: Card, Conversation, Confirmation

New to agile? Remember a user story is more than a card!


How to get the most out of Given-When-Then

Patterns for Splitting User Stories

Splitting User Stories

Story Splitting Cheat Sheet

How to Split A story (mind map)

Twenty Ways to Split a Story

Breaking Down User Stories