Writing application requirements as User Stories: an elegant, simple, user- and value-focussed approach

One of the hardest things you'll have to do when you write applications for customers, directly or indirectly, is capturing the requirements in a form that is understandable for all involved parties. Especially when the projects are complicated, finding a good mode for writing down functionality becomes progressively harder.

There are many things to keep in mind: 

  • Requirements should not be too technical, otherwise the customer will not be able to understand;
  • Requirements should clearly describe their intended goal, so that developers can keep this in mind;
  • Requirements analysis shouldn't deliver huge documents that are hard to maintain;
  • Requirements should describe and prioritize core functionality and cross the bridge between customers and developers;

For the company I work for, we have experimented with a variety of requirements analysis. In this post I want to share some of my experiences. Always stay critical, so don't assume that this approach is the best one around. Also, we're talking specifically about customer requirements, not architectural, performance or structural requirements. Although user stories might work for them, i don't recommend it.

The many roads

There are many ways to analyse requirements. Just a selection of what we've tried throughout the years:

  • Contract-style lists: Basically shopping lists of desired functionality, written down as detailed as possible and signed off by the customer. This works really when you want to clearly draw the boundaries of your efforts for the customer. It also forces the customer to really think things through before starting with the project. The major downside of this approach is that it quickly deteriorates into massive specification documents that are hard to maintain, difficult to understand for customers and - most importantly - ignore the fact that many customers have no clue as to what they want exactly when they ask you to build an application for them. Confronting them with a big wordy version of what they'll get might work for you (the analist), but it does not work for most customers as they can't build a mental picture from a document of what they're going to get at the end of the project. This approach is only useful when the project is small or not very complicated or when you have an amazingly good implementation manager on the other side that can think as abstract as you;
  • Ad-hoc approach: No structured method of writing down requirements. This might work for very small projects, but you can easily get into big arguments with customers about the boundaries of your projects. The advantage of this approach is that it's fast. You only need a piece of paper and a pen or a laptop, and off you go. You could even do without. But how will you make sense of what you wrote down a month from now? Will you still remember the details? An important goal of requirements analysis is to 'download' the desired application from the customer's brain(s) so that it can be used as a reference in the future. Also, for complicated projects (say, something that takes more than a few weeks), this will simply not work;
  • Use cases: Although I like the simplicity of Use cases, they are not as simple as user stories. They are often quite technical, which makes them hard to understand for customers. Also, it takes quite a bit of time if you want to write down 'fully dressed' use cases (see Alistair Cockburn's great book or check [http://en.wikipedia.org/wiki/Use_cases][1]). I think use cases are more effective as a second level of analysis, after the user stories;

Back to the basics

Although we've tried the majority of the above, including other methods, I ran into user stories a year and a half ago. I was immediately struck by their simplicity. An example of a user story is:

"As a shop customer, I want to put products in a shopping basket so that I can order multiple products at once"

A user story capturesa scenario that a customer wants to support in their application in one sentence, using natural language. The user story adresses three questions:

  • Who is executing the scenario (one ore more types of actors)?
  • What can they do (described in the shortest manner)?
  • Why do they want to do is. How does this add value for the actor(s)?

Using this approach, user stories achieve a number of goals:

  • They are simple, because they are single sentences;
  • They are easy to understand for all parties involved, because they are non-technical and very matter-of-factly;
  • They focus on business value (the third question), which allows all parties to understand why this user story is relevant and expand on that;
  • They are easy to write, for a customer (after some basic training) but also for developers, analists or other parties;
  • They are non-technical, which helps parties break free from a technical focus (common for developers) and focus on the user experience;
  • Grouped together, they describe which types of actors or roles should be supported by the system;
  • After a while, thinking in terms of the three questions (who, what, why) becomes second nature. When I listen to customers, I often catch myself identifying user stories;
  • User stories can be grouped into so-called epics or themes; larger groups of related user stories. This gives a good overview of the application under development;
  • User stories can be easily prioritized and fit easily into the Scrum approach (which advocates user stories in general). In this case, you would only analyse a user story in more detail when the user story is assigned to the current or an upcoming sprint;
  • User stories are small enough to jot them down on yellow notes when you're talking with the customer. You could even prioritize them right away by drawing a number of swim lanes for the various priorities and sticking the notes in the desired lane. This will make the requirement analysis sessions with customers more dynamic and interesting;

More examples

Let's take a look at more examples, to get a general idea of what user stories should/could be like (not all of them are perfect, but they'll suffice for the example):

"As a user, I want to be able to register for an account so that I can access content for registered users"

"As a visitor, I want to sign up for a newsletter to stay up to date with the latest news"

"As a shop customer, I want to be able to pay electronically so that I can pay immediatly"

"As a planner, I want to get an overview of employees that are available in a given period, so that I can tailor my planning to their availability"

"As a shop owner, I want to view paid orders so that I can send the products to the customers"

As a content publisher, I want to view unpublished articles and publish them, so that I can add content to my frontpage;

"As an employer, I want employees that have received eight continuous contracts in three years to automatically get a permanent contract, so that I work in accordance of Dutch law"

All user stories follow the same 'as [role] I want to [action] so that [value]' pattern, which makes them easy to read. The final user story also captures a so-called business rule; a bit of logic that makes sense in the customer's domain. I added it here for clarity, but you could leave it out and make it more generic. Business rules are still relevant though, so keep on reading.

There's always a catch

But of course, there is always a catch. The simplicity of a user story is also where it holds the greatest challenge. Writing user stories is not hard, but writing good user stories is. After one and a half year, I still find myself wondering how to capture some aspect of functionality in a correct manner. But I firmly believe that it's better to just start. There's no rule against rewriting user stories during a project if they are unclear. Just keep the following in mind:

  • Don't group too much functionality into one big, clever sentence. The point of a user story is to break down functionality into meaningful scenarios;
  • Don't overdo it either. Writing 100+ user stories is not going to make the application much clearer than a 100 page functional specification document. Although there are many projects where 100+ user stories are needed, it is usually also possible to start with high-level user stories and then work through various levels of analysis. I try to keep our projects between 10 and 40 user stories;
  • User stories arenot a replacement for specifications. Don't work from the assumption that user stories themselves are the same as functional specifications. They provide a good bridge, and a good way of communication, between all involved parties. But this does not mean that writing technical designs, test cases, etc is not longer necessary. Consider user stories as the starting point. When you're talking with a customer, user stories are usually sufficient. But writing down business rules, for example, is still beneficial if they are not implied by the user stories themselves;
  • Don't write user stories for scenarios where no humans are involved. Sometimes, you want to describe functionality that does not really involve real people. For example, when you're describing functionality that involves the sending of data between two webservice. Now, you can write the user story like 'As webservice A, I want to send data to webservice B so that I can ...'. I don't like this approach. Ultimately, every user story should describe something that is related to a user performing some action, so the user story should always involve a real person. That a lot of magic with webservices happens behind the screnes is irrelevant;
  • Try to refrain from technical descriptions, like 'As a visitor, I want to click a link to open a contact form so that I can get in touch with the owner's website'. 'Link' and 'Contact form' are technical terms, that might not make sense to a customer. As a website developer, it's easy to think of a site in terms of a bunch of pages. But this is not always so clear for customers. Avoiding technical descriptions also leaves open how to exactly implement the scenario. There are usually many different ways, and a technical approach will narrow down the options. You might even end up with user stories that are performed manually, because the cost of implementing them are too great. So instead, just stick to what the user wants to do and why: 'As a user, I want to be able to contact the owner of the website, so that I can get in touch with them';
  • There's not one right way. So whatever you read, including this blog, actively consider how useful user stories (and a particular form) are for your application. If you're building something that hardly involves real people doing stuff, than user stories might not work very well. The same goes for very simple or very complicated environments;

Expanding on requirements

As previously mentioned, user stories are a good starting point for describing requirements. Per user story, the following is useful:

  • Describe acceptance criteriasfor the customer for the user story. When is the user story implemented correctly for the customer? We recently had a customer that wanted visitors to be able to upload Word documents into a rich edit and strip them of all formatting so that they could re-use already typed documentation. The acceptance criteria in this case was that it had to work like WordPress' implementation which strips all formatting but leaves the structure intact;
  • Describe business rulesassociated with the user story. Writing down business rules is a good topic for another post, but the essence is that you need to write down what logic the customer uses. For example, some of our webshops don't allow orders below a minimum price. This is a business rule that is relevant when shop customers can place their orders. The nice thing about business rules is that are very easy to translate into test cases;

Some uses of user stories advocate creating small visual sketch for every user story, like a login box for a user story related to user login. Although useful, I think this only works for very small applications with very small user stories. For large applications, this would require very fine-grained user stories and - as a result - a huge number of them. But then again, it all depends on the context.


User stories use natural languageto capture aspects of core functionality in terms of scenarios that are performed by users. It does this by adressing three questions; who is performing the scenario, what are they doing and why are they doing it. User stories are a great and simple way to capture complex functionality in a manner that can be understood by technical and non-technical parties alike. Moreover, they focus on business value by asking the 'why is this important' question for every user story. Keep in mind that user stories are not a replacement for huge detailed specifications. These documents might be still be useful, and you could set up these documents based on user stories (like we used to do). But user stories are at their best, when they are kept to their bare essentials. Good luck!

Christiaan Verwijs
Christiaan Verwijs

Scrum Master, Trainer, Developer & founder of Agilistic