This post was originally published on the Scrum Alliance Community Articles

User stories are, well, stories. This should be obvious, but, unfortunately, it isn’t.

They are not statements, such as “Build a new front page.” They are a story. Stories have a hero or heroine, a goal, and a quest.

User stories are not riveting, but they tell us, from a user’s perspective, what the user is trying to accomplish and, more importantly, why. They are not absorbing novels; they take the form of only three lines.

Here I want to go through my understanding of what user stories are, how to write one, and when to use one. User stories are just like any other tool — there are times when you should use them, and times when you shouldn’t.

How it all began

In Waterfall, the first thing developed in software was the “requirements specification.” (Some of us, myself included, still write these today.)

This formal document described, in intricate detail, what was needed in the development. Who was responsible, who wrote, who changed things. If you were lucky, it also included the why. The document was used as a way to get agreement from the customer on what the development was supposed to be.

It sounds logical to think through what needs to be developed before you start the work. Making it formal makes it, effectively, a contract. In most cases it did become the contract. It also allows you to figure out up front how much effort is involved.

The problem was that, once development started, people would change their minds. Customers would have changing requirements. For a project that lasts six months or more, priorities can shift. What was business critical when the requirements were written can become irrelevant by the time feature development started. The difficulty of what needed to be done could be significantly more than what was initially envisioned. Agile came about to handle this situation from a development perspective, but something needed to be done from a requirements perspective. A requirement was still needed — developers needed to know what to build, but they didn’t need a detailed specification, just enough information to have an idea of what the customer was thinking so they could get started. The details could be worked out along the way, through talking with the users.

So some bright spark developed the idea of using a story to tell what the user was trying to achieve, and the practice has developed over the years.

Why use user stories?

One of the most obvious reasons to write user stories is that they are only three lines long (in the classic case), as opposed to being a formal document of several (or more) pages. That means there is less administration. You don’t need to update the user stories.

Now I know what some of you are thinking: A user story is only three lines long, so it cannot have much detail compared to a traditional requirements document. You’re right. They don’t have the detail, but that is the point. A user story is not a replacement for a requirements document, it’s a trigger to have a conversation with the relevant people, when required, about the requirements. In fact, the idea is to have continuous collaboration with the customer through discussions, and ongoing confirmation to keep refining the product.

Since user stories are small, they are also easier to estimate accurately.

User stories promote smaller iterations of work. With smaller iterations, you can get feedback sooner, which helps the refining process. It also allows you to change priorities as needed, without significantly affecting other pieces of work already in flow.

The INVEST principle

To explain all this a bit more clearly, we have the INVEST principle. INVEST names a list of principles that each story should adhere to so that we get the most out of each story and can write them better. INVEST is an acronym that stands for:

• Independant. Each story needs to be independent of the other stories. This allows stories to be prioritized separately and cuts down on dependencies. For example, you cannot complete one story if you are waiting on another story to be complete. Or you cannot test a story if it is dependent on another story.
• Negotiable. Teams need to be able to negotiate stories with the product owner. Circumstances change, and the team or the product owner needs to be able to reconsider how the story is both implemented and scoped. An example may be that the story is not technically possible. (Howevr, even though the story can be negotiated, the product owner still remains accountable for it.)
• Valuable. A story must have some value to the business. This is to prevent additional features from being developed that end up being of no use, or that the developer thought were good ideas at one point but have since become of no value.
• Estimable. The story needs to be written in such a way that the team can estimate how much effort is involved. This tries to avoid the problem of scheduling or making promises based on inadequate information.
• Small. Stories are small increments of functionality. This helps helps the project be built by small bits of value at a time, rather than by large chunks that might end up not being used.
• Testable. This helps make the requirement a known entity. It gives you something that you can verify. It is part of the Definition of Done. It is to prevent stories such as, “Write requirements” and prevents ambiguities such as, “The page must load quickly.” Instead, a measurable requirement is given, such as, “Must load within 10 seconds.”

Now that we know the principles of a story, how do we format them? There is a formula.

3 C’s Formula

The 3 C’s formula outlines how stories are put together. They are:

1. Card: User stories are captured on a card (usually a 3×5). The description is on the front, and the acceptance criteria are on the back.
2. Conversation: The card is a trigger for discussion of the requirements among:
   • Team members
   • Team members and the product owner
   • Team members and stakeholders\users\customers
   • All of these groups
3. Confirmation: Finally, the user story helps the team discuss with the product owner how to determine when a feature/piece of work is complete.

Now we come to the juicy bit.

How to write a user story

So, to summarize, user stories are a description of a requirement in story form, from the user’s point of view. They are not written from the developer’s point of view, nor that of the product owners, but from the point of view from the person who is actually going to use this thing.

User stories are also short and succinct. They do not waffle on (like this article).

However, they can take one of many forms. Here are a couple of useful templates.

User story templates

The following is the classic version: As a [role]
I want to [requirement]
So that [reason/ROI]

The role is the “who,” our hero/heroine, the user. The requirement is the “what,” or quest, that our hero/heroine is trying to achieve. The reason/ROI is the “why.” Why does the user want the requirement? What is he or she trying to achieve? In other words, what is the goal?

An example based on a traditional story could be:

As a member of the Rebel Alliance,
I want to destroy the Death Star
So that I can save the galaxy.

Another variation on this template is the “In order to” template. It goes like this:

In order to reason/ROI
As a role,
I want to requirement.

Same information, but different wording. These are the more traditional ways of writing user stories, but they are not the only ways.

Comics

I attended a seminar at Elabor8 on using comics as a method of writing user stories. As they say, a picture is worth a thousand words, what better way than with a comic strip?

Can’t draw? It doesn’t matter. Use stick figures. Alternatively, if you are really worried about your drawing ability, try photos.

Movies

With the prevalence of smartphones, we almost all now have a video camera in our pocket. So, if it makes sense, why not act out the scenario of the story? It’s another way to express the requirements, and who knows, it might be fun. You might even be able to record a statement of the requirements, if the product owner is willing.

These methods can then be captured in your software-based backlog if you use something like JIRA, or you can put them on a web server, and print out links for physical cards, or insert links in electronic ones.

The whole idea is to try different things. See what works. If it’s a waste of time, you’ll know quickly; but it might boost your understanding of the story.

Impact mapping

One tool I like is Impact Mapping, created by Gojko Adzic. An impact map is a type of mind map that allows you to brainstorm and explore scenarios. “Branches” are then trimmed based on the team’s ability to implement them. Ultimately you are left with the branch you will implement. The impact map is drawn in such a way that you have who the feature is for, why the user wants the feature, and finally the “What” and “How” you need to do the feature. This is what the user wants.

An example of an impact map is below:

With an impact map, you start of with the why. Why are you doing this? In the above example, we are trying to save the galaxy. Next, we look at who is trying to achieve the goal. This would be our user, the our hero or heroine. In this case, it is a member of the Rebel Alliance. Next we have the how we are going to achieve our goal. This is where the brainstorming really starts. List as many ways as you can think of to achieve the goal. It doesn’t matter if they are realistic, just write them down. Who knows, they may lead to something.

Finally, for each how list, what needs to be done. Keep everything at a high level. We are not trying to solve every branch, only to get an idea of what is involved.

Once you have your impact map, you start trimming branches. Something may be impractical. Something may not be ready to do. Something may require resources that you do not have.

Eventually, after several iterations, you should have a single path to follow. But don’t spend too much time on this map; it is just there to give a visualization of what needs to be done, along with alternative views. You still may end up selecting the original proposal, but it will be a definitive answer with alternatives having been explored.

Now that you finally have the Why, Who, How, and What, you can write your story:

As a member of the Rebel Alliance,
I want to destroy the Death Star
By Sending two torpedos down an exhaust pipe that has been found to be a weakness in the Death Star’s defenses,
In order to save the galaxy.

Now that we’ve filled out the front of the card, it is time to look at the back.

Acceptance criteria

On the back of the card (or its software equivalent), you have the acceptance criteria. It outlines how the story will be verified as Done by the product owner. This needs to be hard criteria, not anything ambiguous. It’s best that the criteria be testable. If you can test it, you can define it.

Just like the story, the product owner is responsible for writing the acceptance criteria (with consultation from the team). For example, business analysts can help write the acceptance criteria, but it is up to the PO to accept them. Sometimes the acceptance criteria are used as part of the Definition of Done.

Acceptance criteria template

Just as there is a template for the user story, you can use a template for the acceptance criteria. An example:

A [role] should be able to:

• [Acceptance Criteria 1]
• [Acceptance Criteria 2]
• [Acceptance Criteria 3]

Edge cases:

• [Edge Case 1]
• [Edge Case 2]

Separating out the edge cases helps your thinking process. You work on the normal cases first, then brainstorm the edge cases.

This acceptance criteria is a placeholder for further discussion to get confirmation from the PO. Then more detailed acceptance criteria can be determined.

Gerkins and Cucumbers

For acceptance criteria, I like the Gerkin language. It was initially developed for use by a program called Cucumber. Cucumber is a behavior-driven development program that allows you to specify acceptance criteria in plain English, then execute those statements as tests. Yes, execute!

Gerkin takes the form of “Given, when, then” statements. The Given section is your preconditions. It’s where you set the stage for what needs to be done. The When section is when you actually do something to the preconditions. The Then section is where the expected effect is described. For example:

Given two numbers, 1 and 3,
When I add these two numbers together,
Then I expect the result to be 4.

Nice and simple, easily understood not only by developers but by anyone who can read.

Now, I mentioned that Gerkin is used by Cucumber, but that is where it started. There are now a number of products that use this language to produce executable specifications. These include, but are not limited to:

• JBehave
• EasyB
• Gwen

The beauty is that you don’t need to use these products to get the benefit. Just writing your acceptance criteria in this format means that it’s easily readable, verifiable, and future proof. So, for example, if in the future you wish to use one of the above products to make the acceptance criteria executable, the writing of the tests is done.

There are other types of programs that also allow you to write executable acceptance criteria. These are more free form and allow you to do more traditional documentation; Concordion and Fitnesse are examples.

Concordion uses HTML pages to write the acceptance criteria, and Fitnesse uses a wiki.

With most of these products, to make the specifications executable, bridging code is required to allow the interpreter to execute the tests. Usually the bridging code can be simple and reusable. But determining the complexity depends on what type of application you’re writing. I won’t go into how to write these, but I recommend investigating them anyway.

Epics and themes

Now we come to stories that are too big to fit into one sprint. These are called epics and themes.

So . .

What is an epic?

To put it simply, an epic is a very large story. Not in terms of description, but in terms of implementation. An epic is a story that can take more than one sprint to complete.

In the “Story World” (going with our Star Wars theme), an epic would be the Star Wars Trilogy. The epic in this case is made of (originally) three stories, Star Wars, The Empire Stikes Back, and Return of the Jedi. Each of those stories is watched in one sitting, just as a story will be done in one sprint.

What, then, makes a story an epic? There can be a number of reasons: A story may be at a very high level and need more information. Usually when the backlog is first created, all stories are considered epics. In other words, the epic is used to capture requirements at a very high level. Another reason could be simply that the story ended up being bigger than you initially thought, and therefore it cannot be completed in one sprint.

Epics are not the only way large stories can be described. We can also use themes.

What is a theme?

A theme is a collection of stories that have a shared attribute. For example:

As a Star Wars fan,
I want a group of pages to explain the movies
So that people can learn more about the Star Wars movies.

Here, the word group insinuate that the PO wants more than one page. So, this theme can be broken down into:

As a Star Wars fan,
I want a “New Hope” page
So that I can see details about the first Star Wars movie.

As a Star Wars fan,
I want a “The Empire Strikes Back” page
So that I can see details about the Empire Strikes Back movie.

and so on. As you can see, the two stories are identical except that they discuss different movies. The theme here is that they are both pages about Star Wars movies.

Again, just like epics, themes generally cannot be completed within one sprint, unless of course the stories are quite small. This means that the stories themselves are completed in the relevant sprint, but the theme, just like an epic, is completed over multiple sprints.

Splitting and combining stories

So now that you know what an epic and a theme is, there may be times when you want to split an epic or theme into smaller stories, and there may be times when you want to combine multiple stories into an epic or a theme. Remember, an epic or a theme is still just a story.

When to split stories

Most of the time, you will want to split a story because it cannot be completed within one sprint. The work is too large for one sprint, so you split the story into two separate stories. You complete one story in the first sprint and the other story in the second. The original epic or theme is then complete.

Another reason to split stories is to get a more accurate estimate. It might be too difficult to estimate a piece or work, so break it down into more manageable chunks, then estimate the chunks individually. Estimating smaller chunks is easier.

How to split stories

Splitting stories can be tricky, simply because there are so many possible ways to do it, and not all of them result in split stories that make sense. Here are some examples.

Does not meet performance constraints. Let’s say you are building a web page that has to load within five seconds. Building the page is easy, but let’s say that the performance of the page will prove difficult; to make it load within five seconds is extremely hard. What do you do? Split the story. The first story is the building of the page. This gives the product owner value. They have a page that the end user can in fact use. The next story is the performance criteria. This will be tackled later. Maybe the next sprint, maybe five sprints later, maybe never, if it turns out that the customers don’t care that the page takes 20 seconds to load.

Separate or mixed priority. This is when some of the acceptance criteria is of higher priority than other acceptance criteria. Split the story based on the different priorities of the acceptance criteria. Do the higher-priority stories first and leave the lower-priority ones until later.

To remove crosscutting concerns. This is when a story has acceptance criteria that applies to more than just that one story. Logging, error handling, and security are examples.

When to combine stories

There may be times when you would like to combine stories. Perhaps the stories are related and both could be completed within one iteration. For example, in transactional processing, you may want to combine the pick-up and drop-off of a transaction in one story. You may also want to combine stories when you want to prioritize them as a group. For example, two stories need to be completed together.

How to combine stories

There are a number of ways to combine stories. They are all similar.

• Create an epic and then refer the individual stories to the epic.
• Create a new story, so long as it can fit within a sprint.
• Create a theme if it is a set of related stories.
• The whole idea of splitting and combining is to refine the backlog. Combine stories so that twp people do not put the same amount of effort into one story, only to find that the other is similar enough they could have been done in one. Split stories so that larger chunks of work are broken down into more manageable sizes.

Conclusion

In this article I have tried to show how stories work and how they should be used. Take from this what you are most comfortable with, but if you do use stories, make sure you know the correct terminology, what a story is, and how to use it. That is the knowledge I have tried to give you, based on my own understanding. If your understanding of stories is different, please let me know in the comments. We are all learning, and the best way to learn is to share knowledge.