User Stories

This post is about user stories. Since they were invented, they have become the building block of Agile iterative and incremental development approach. Let’s explore a bit of their history, their rationale, how we should record and ultimately use them.

Kent Beck's Idea

Let me describe first the way requirements were written when I started developing software (early 2000’s). In every team, there were analysts that got together with business people so that they could tell them the problems they had and the functionality they needed. These analysts wrote these ‘requirements’ in a big ‘specification’ document that was later handed to us developers. From there on, us (devs) were supposed to use this specification document to write the software in accordance. As you can imagine, there were serious communication problems and a great deal of waste in this process. As Jeff’s famous image describes, everyone on the team (analysts, devs, testers, etc) understood different things!

Kent Beck’s simple and wonderful idea was bringing business users to tell these problems/functionality expected in the form of stories directly to the developers. What he said is that these stories told by users that know what they are talking about would create interest and vision in the team. It would allow everyone to understand the real needs, to ask questions and to design solutions together. The conversation is the key part of Kent’s idea. Moving away from creating documentation (by an analyst in a previous step) to telling stories and having conversations.

Ron Jeffries described in Extreme Programming Installed the way stories fit into the XP methodology using the “card, conversation, confirmation” formula:

1. Card: Each time there was a story to tell, a card was written as a token that reminded us there was a conversation to be held (Alistair Cockburn named these cards tokens for conversations).
2. Conversation: This is the key part of working with user stories. The moment for the ‘What about …?’ questions (Hussman used to say), the moment to talk about the feasibility, the design of the solution, the alternatives. Patton stressed that ‘story conversations are about working together to arrive at a best solution to a problem we both understand’.
3. Confirmation: When the team understands what is needed well enough, they write a set of acceptance criteria that defines how this story will be validated.

This is the story with stories. Let’s talk a bit about how we remember these stories.

Rachel's template

Reading Jeff Patton’s User Story Mapping book (the best book on user stories if you are looking for something to read, in my opinion) I discovered that the famous template all of us use was presented by Rachel Davis and her team in Connextra in XP2001. Their motivation was standardizing a template that summarizes the most important information about a story and also allows the dev team to find the stakeholders when needed.

The template is something like this:

As a <user>
I want/need to <do something>
So that <some reason>

Rachel’s template has some nifty attributes. It encourages us to write the story from the perspective of one of the users therefore using its lingo (their domain vocabulary). This, in turn, makes us ask the questions needed to understand the domain. It encourages writing something these users want or need to accomplish. It does not have implementation details, as these should be discussed within the team. Finally, it encourages us to define why we need that functionality, what is the desire, the expected benefit. Many times, when business users tell them this, developers imagine alternatives to achieve the same benefit in cheaper ways. In summary, this template encourages us to specify who, what and why for the story.

This template became very popular. So popular that many of us believe that we needed to write stories this way to be ‘user stories’ and we needed to fit everything inside the card (Note how I used ‘card’ explicitly as Jeff does in his book, to differentiate from the story) with this template. Of course not. The card is just the summary. There’s much more than the card: the User Story Map, diagrams, personas, wireframes, etc.

Acceptance Criteria

The above template is not enough to describe the scope included in a story. You need to add the acceptance criteria, the confirmation, a set of conditions that allow the team to tell if a story has been completed. This criteria often comes as examples which, if executable, become living documentation (as coined by David Evans).

There’s a template, well know to people that write automated tests, that uses the Gherkin language:

Given <a set of pre-conditions>
When <an action or event occurs>
Then <a few things happen>

Again, this is not the only way of defining an acceptance criteria. You may write mockups (or even complete designs), point to diagrams or do anything that lets your team understand the story as well as possible.

Attributes of good stories

Many of you probably know Bill Wake’s INVEST attributes for good stories. They need to be independent, as this allows you to work on them in any order. Negotiable as they are not a contract (there’s space for conversation). Valuable to the customers. Estimable, as estimations help customers rank and schedule them. Small (a few days of work). And finally, testable (if customers don’t know how to test it, probably the story isn’t clear enough).

Those are really good attributes, but sometimes difficult to explain and follow when I work with teams. I made a few adjustments that I’d like to share with you. Stories have dependencies. All devs know that. Telling them to try to make them independent hasn’t worked for me so I don’t use it. Valuable also brings misunderstanding sometimes, specially when we break stories as all broken stories share the same value. Nonetheless, many times, dogmatically I found myself trying to add silly reasons just to fit the template. I don’t do it anymore. I now prefer to say that all stories should have something visible that allows the Product Owner to be involved in the development (i.e. as long as we understand why the functionality is needed, I don’t get crazy to fill this section). Finally, I always felt that estimable & small were very similar. I used to say that stories should be manageable, in a planning and an iteration, but I’m not sure if it was a good idea. Nowadays, I prefer to say they should be small. We want stories that we understand (therefore can be estimated), that fit well in iterations and for which feedback can be provided soon.

Slicing stories

We may end up with stories that are too big and therefore we need to break them. To slice stories, you just need to understand thoroughly the iterative and incremental process. There are many tips on the web. I’ll share a few:

• Break from the GUI: meaning doing something with the functionality, but without the design and another that holds the design.
• Break the error management conditions: One for the happy path and one to take care of the exception logic.
• Break into logical sets of data: if there are sets of related information, we could split them into different stories.

Notice how sometimes we break stories to iterate (we build something knowing that we will need time to go over it again, as in the case of the first 2 tips) and some others to increment as in the last tip. The Agile process is a mixture of both the iterative and the incremental approach. Also notice what I just mentioned about the value of these stories. It is the same for all broken stories. In fact, it’s the value the user told us. Therefore, don’t bother adding this same value in each of the broken stories.

When we break stories, it’s important to make sure that everyone in the team understands what is included in each of the broken stories, so that we can code, test & validate only what is included (but do it thoroughly).

Writing Stories

There’s always the question of who should write the user stories. In Scrum, the obvious answer is the Product Owner as is the person that knows the users and can describe the value expected better. However, based on my experience, they often don’t have availability or even the experience to do it. In these cases, someone from the team must help. As a scrum master or tech lead in my teams, I like to do these things. If there are no volunteers, the team may make it a shared responsibility. In the latter cases, make sure the Product Owner understands what is written, how stories are broken and what is included in each card.

Indistinctly of who does it, let’s think what we want to accomplish when we record stories. We’d like to store them in a way that everyone remembers them in the best way possible: we understand the scope of each broken story (what’s included and what’s not), how we will test it, how we will know if it’s finished, etc. And we want to do it using the least amount of energy, so it should be in just one place, easily accessible and that allows us to edit it (and prioritize it) rapidly.

There are tools that I use to record stories with the whole team which I really like because they are really easy to get started with, they are visual, they are tactile and they encourage the collaboration amongst all members. When the team participates in recording these stories, they will remember them better. Jeff Patton says this documentation becomes vacation photos which people that have the context (that were there at the moment of taking) can understand as it evokes memories.

The first one is obviously the User Story Map. I love this tool as it lets me easily record the most important steps of a story in a very visual way (as we can visualize the order of the steps). The team can collaborate very effectively and have conversations in front of the map, leaving the decisions which trigger new conversations (it’s a virtuous cycle). It lets you swipe horizontally your product fastly, leaving the deeper discussions for later and it lets you prioritize, decide which are the most important steps, the ones that should be built first.

Another tool is example mapping, which I learned from Matt Wynne at XP2016. This activity structures the conversation and lets you visually record stories with their examples, rules and questions. Using different colors for these components allows the team to visualize some smells. For example, when there are too many rules/examples then it’s a smell that the story is too big and if there are too many questions it may mean the story is not ready.

A final tip. Introspect and get better at writing stories. Are you using the best tools? Are you easily finding what you record? Are you duplicating information? Are there better ways of doing these things? Encourage self-organized teams to inspect & adapt, to try new tools and activities, to experiment!

Definition of Done/Ready

There's a couple of definitions that could be useful at the moment of using stories to develop.

The ‘Definition of Done’ is a list of criteria that the team considers need to be completed in order to accept this card. As it applies to all stories, it doesn't make sense to include it in all of them. However, it does make sense to explicit this criteria to make sure everyone on the team understands the same. With some teams, I facilitated an activity to write the criteria and leave it visible in our open space and lately with the pandemics, in our Miro board. This information radiator is useful at the moment of accepting the first few stories.

Another definition that may be useful, specially (in my opinion) in complex environments is that of the ‘Definition of Ready’ which means the card is ready to start development. In other words, the team understands what needs to be coded, how it will be tested and also knows there are no blockers or dependencies pending (remember we can store not ready cards in the Product Backlog).

The Backlog

We usually store our cards in an artifact called Product Backlog. The magic of this artifact is that it is very lightweight and it allows us to store the user stories in any state of refinement, starting from just a title until the card is ready for development. It also allows us to prioritize (record the prioritization agreements) very lightly, just dragging and dropping (same that happened with physical cards in XP). Finally, it allows us to leave their estimates (which, as mentioned above, could be used to decide on the prioritization). Formalizing, the Backlog is a prioritized list of estimated story cards. We use it to store, communicate, share and mainly manage the cards throughout the construction process.

Do we really need Agile Management Tools?

Let me tell you something that has been bugging me lately with Backlogs and Agile Management tools. I really like them (I have been using them for many years), I really do. However, lately, I feel that many times these tools push the team away from what is really important, the users and the product and start dictating our thought process. Let me dig deeper:

• The way we store the cards isn't really visual. Way too many times I see teams struggling to store conversations in the card and losing sight of all the other vacation photographs they build before. Sometimes, there are mockups, story maps that are forgotten because the team only uses their preferred Agile Management tool.
• There’s waste at the moment of writing stories based on previous artifacts created in the discovery. Many times, it seems that we need to extract the information from other tools to write it in the template and the result is much worse.
• Devs start thinking about tickets. They need tickets to start working and these tickets need to have ‘all the information’. I get mad when these things happen because I want devs that get involved, that require having conversations with users, that explore options, that design together with business users.

Let me tell you another reason. Since the pandemic, I started using Miro boards in the Discovery phase. After finishing the discovery, when people started telling me that we needed to move this information to an Agile Management tool, I started doubting if it was worth it. There was so much information on the board, so many diagrams, so many images, so many vacation photos. It really felt like our old open space. On top of this, I also knew that after migrating this information to the Agile Management tool, the team was going to forget about it. At the minimum, its radiation power will be diminished. The team told me that we could use both tools, each for their purpose, but it doesn’t feel this way to me. And I have the feeling that many of the problems I mentioned above would be gone if we just use the board. I’m not sure I will convince you to drop your Agile Management Tool (in fact, I haven’t convinced anyone yet). But perhaps I made you think about how you are using it. That’s enough for me.

Final tips

The most important advice is to never stop talking with business users. There’s nothing like listening to their stories first hand. It’s the best way of understanding their problems, their context and thinking together about the solutions.
The second one is to record these stories/conversations/agreements in the most efficient way. Draw, take pictures, use mockup tools, wikis, boards. The digital world is full of great tools now, use the best ones. And get better at doing it. Discuss with the team what is working and what could be improved. Look for sources of waste. Inspect and adapt.