User Stories: Documenting Requirements in Agile

User Stories: Documenting Requirements in Agile

What makes a good story? A good story is one that grabs the reader’s attention with a captivating hook, an interesting plot with conflicts and dramas, a vivid and immersive setting, and multifaceted characters who face challenges and resolve them throughout the narrative.

Well, that’s not the case with user stories. They don’t have all these elements (except for the characters), but user stories don’t need them to play an important role in software development. Being an indispensable part of Agile philosophy, they reflect its core principles of inspiring creativity, fostering collaboration, and focusing on the end user’s needs.

As you might have already guessed, this article is dedicated to user stories. We’ll talk about what they are and explain in detail how to write and manage them.

What are user stories?

User stories are a way of describing the functionality of a software product from the perspective of the end user or customer. They were introduced in the late 1990s by Kent Beck within the Extreme Programming framework as an alternative approach to documenting requirements.

Importantly, a user story doesn't describe the feature itself or how to develop the functionality but rather defines the user’s need – the end goal, thus leaving the development team room for creativity in implementing the feature.

User story format

User stories are short, simple, concise statements, usually written in an informal style. They outline the who, the what, and the why behind the feature being developed. Even though there can be room for flexibility in how to write them, the common standard is a single-line sentence in the following format:

As a <type of user>, I want to <perform some action> so that <some reason or benefit>.

how user stories work in everyday life

Agile families be like… Source: Geek&Poke

In other words, each user story includes a specific user persona, the intermediate operation they want to do, and the desired outcome they want to achieve.

User story examples

It’s easiest to understand user stories through examples. Here are a few cases related to software usage (even though you definitely can write user stories about buying those chocolate doughnuts or throwing a Friday night party).

As a project manager, I want to track team performance weekly so that I ensure on-time delivery.

As an online shopper, I want to filter products by price, category, and rating so that I easily find what I need.

As a traveler, I want to choose airplane seats online so that I sit with my friends.

As an online gamer, I want to see health information all the time on the screen so that I conveniently monitor my status.

As a passenger, I want to see the driver's phone number so that I can call or text him/her in case we don’t find one another.

As a social media user, I want to add a picture to my profile so that other users know what I look like.

As a credit card holder, I want to see the list of recent transactions so that I control my spending.

As a diner, I want to see the restaurants on the map so that I choose the nearest one.

Note that some user stories (especially related to backend functionality) won’t have the end customer as the actor. In this case, the user story can be focused on the business user, like the system administrator or executive. As Dmytro Hurkovskyi, a Business Analyst at AltexSoft, jokes, “Anything can be written down as user stories. If someone can’t write a user story about something, they have to go get additional BA training.”

User stories in Agile

User stories are an essential component of various Agile frameworks, supporting the philosophy of putting the users and their needs first (instead of the coding process or tech documentation). As part of the Agile philosophy, they help create a shared understanding of what the user wants, supporting collaboration between team members and other stakeholders on how software can deliver this value.

User stories as part of the backlog

In many Agile frameworks like Scrum and Kanban, user stories are the core elements of the backlog. From the developers' team perspective, user stories – or backlog items – can be seen as the piece of work needed to be done during one iteration.

And that’s what makes user stories so crucial since teams basically organize their project activities around them. They are also essential for backlog grooming and making project estimations that we’ll talk about a bit later.

User stories vs use cases

As we mentioned, user stories essentially originated within Extreme Programming as a way of managing requirements that are alternative to use cases. And the similarity of the two terms often causes confusion. User stories are sometimes even used interchangeably with use cases because both describe how the user interacts with the system. However, they have some important differences in format, purpose, and level of detail.

Format. Unlike the succinct and informal user story format, use cases are typically written in a more structured and formal way, including such elements as actors (it can be the user or another system), preconditions, system (functional requirements), triggers, alternative flows, postconditions, etc.

Level of detail. User stories are very brief and only outline the user’s intention, while use cases are much more detailed and give more context.

Purpose. Use cases determine and formalize the functional requirements, outline the project scope, and give engineers in-depth guidance on the development process. Meanwhile, user stories provide general development direction and help keep everyone on the same page (both technical teams and nontech stakeholders).

As Dmytro Hurkovskyi explained, “User stories actually evolved as successors to use cases. They allowed mature Agile teams that don’t need detailed use cases to reduce the time for documenting requirements. However, in reality, a hybrid model is often implemented, and some context is added to user stories to provide developers with more guidelines.”

User stories vs epics vs tasks

Different teams use various approaches to structuring their work. A common scenario is breaking down the entire project scope epics, user stories, and tasks.

Agile work breakdown chart

Epics, user stories, and tasks hierarchy

An epic can be defined as a group of user stories that makes up a greater body of work that’s usually done during several sprints. So an epic isn’t about a specific issue but rather about an entire flow like registration, profile management, search, booking, payment, etc.

Meanwhile, a user story can be broken down into tasks which are the smallest segments of work that have to be done to complete a story.

You can also encounter the term initiative which is basically a high-level objective that is to be achieved as a result of the project (e.g., launch a product to market or increase company profit by X%). Some teams use initiatives to describe a set of epics.

Now that you have an idea of what user stories are, let’s get more practical and see how they’re created.

How to write user stories?

First and foremost, let’s rewind back to the origin and look at the three key aspects of user stories known as the 3 Cs.

The 3 C’s of user stories

Ron Jeffries, the founder of Extreme Programming, proposed a so-called 3 C formula, describing the three essential components of user stories: Card, Conversation, and Confirmation.

The 3 C’s of user stories

The 3 Cs of user stories

The card refers to a tangible representation of a requirement since, initially, user stories were hand-written on index cards which could then be moved around while prioritizing the backlog, handed to developers who work on the related task, or given to the customer upon task completion. The cards rarely give details on the requirement but define the intent and serve as an invitation to conversation.

The conversation occurs over time (often during the iteration/spring planning) when the team members (and other stakeholders) share thoughts and opinions on the story under discussion. The conversation is necessary as it helps develop a common understanding, set the objective, and make estimations. The conversation is largely verbal and can be supplemented with documentation.

Confirmation refers to conditions under which the user story will be defined as accomplished, and the objective set during the conversation is achieved. They are also known as acceptance criteria – that we’ll describe in a bit.

User story best practices and the INVEST quality model

Here are some practical guidelines on how to write great user stories.

Keep it simple. Stick to the concise, informal format of user stories and avoid unnecessary details or tech slang. This way, you’ll be able to engage different stakeholders in a productive conversation.

Avoid ambiguity. Well-written user stories are clear to stakeholders and don’t allow for multiple interpretations.

Put the user first. Instead of focusing on the business or technical aspects, always keep the user perspective in mind.

Start with epics. Epics are a great way to capture the big picture of the product functionality. You can then break them down into smaller, more specific user stories that are easier to manage.

Determine user personas. Define the type of user who interacts with the product based on market research. If there are multiple user types – write multiple user stories.

Encourage collaboration and feedback. Let all stakeholders communicate their thoughts and opinions on what a product should do so that you can develop the best solution that satisfies everyone.

Refine user stories. Conduct a regular backlog grooming, i.e., constantly review your user stories to ensure they are relevant and prioritized.

Ensure they follow the INVEST criteria. INVEST stands for a widely accepted checklist that helps assess the quality of user stories. So make sure they are

  • I – Independent (each one shouldn’t depend on others so that they can be done in any sequence and not affect one another if changed),
  • N – Negotiable (there shouldn’t be a rigid workflow but rather a room for conversation and adjustments),
  • V – Valuable (each user story must bring value to the end user),
  • E – Estimable (the team should be able to estimate the effort required to complete the user story),
  • S – Small (each user story shouldn’t take longer than one sprint to be completed), and
  • T – Testable (it’s possible to define at least one acceptance criterion to confirm the proper completion of the user story).

Add acceptance criteria. Detail specific conditions that must be met to consider the user story complete.

Acceptance criteria compose a broad and important topic that deserves going into more detail. Check out the linked article to learn about their purposes, formats, and best practices, or watch the video explainer below. In this post, we’ll provide a brief recap of the key points.

Explore acceptance criteria together with Harry and his friends

User story acceptance criteria

Acceptance criteria (AC) are a list of conditions the developed product must meet to define the user story as “done.” These criteria help everyone involved understand that the product satisfies the client’s and end user’s expectations. They also clarify requirements by adding details to user stories, thus providing engineers with better guidance through the development process.

AC must be created for each user story before the team starts working on it. They must be written in short, clear statements, each having only a pass or fail result (there can’t be partially fulfilled AC). Commonly a product owner and a business analyst are responsible for writing AC.

There are multiple AC formats. The two most popular ones are scenario-oriented (Given/When/Then structure) and rule-oriented (a list of rules that describe the system behavior). Neither can be considered a perfect, universal solution since there are cases when one works better than the other.

Acceptance criteria examples in two formats

Acceptance criteria examples

In addition to facilitating development, AC also serve as a basis for acceptance testing.

User story templates

Now that you know everything about creating user stories, you can write them in any medium that’s convenient for you, whether it’s sticky notes, a Microsoft Word document, a digital notepad, or a whiteboard in your office. Here are a few downloadable templates suggested by Aha! to let you choose the format and detail level (they'll automatically download when you click on them).

Another way – and arguably a more efficient one – is to create and manage user stories in specialized software. We’ll talk about some digital tools further on – right after we discuss what other actions can be done with user stories.

How to work with user stories?

Let’s zoom out a bit more. You can’t just write user stories and then forget about them. They have their own lifecycle within the project so they have to be managed properly. So let’s track the entire user story evolution and start with the question that always bothers parents and cops – who is responsible?

Who writes user stories and when?

Typically, it’s the product owner/product manager who writes user stories – and it’s also their responsibility to build up a backlog. Often, product/market fit research is conducted with the help of business analysts to find out the consumers’ needs – to be then converted into requirements in the user story format.

In reality,however, it’s not that simple and straightforward. The very nature of user stories is cooperative (remember the conversation part?), so all stakeholders are expected to participate in their development. And that’s only natural. It’s a common case for a client to come up with ideas on the value the product should bring to the end user. On the other hand, team members often suggest ways to improve the developed software – and add new user stories to the backlog.

As for when, usually, the majority of epics are written at the initial stages of the project (the so-called discovery phase) and then broken down into user stories. Dmytro Hurkovskyi shared, “User stories are being continuously developed during the entire course of the project.

It’s important to remember that user stories aren’t strict requirements and evolve during the project. We've already explained that teams often add more details to user stories as they prioritize them in the backlog. Also, when the team starts estimating specific user stories, it might turn out that some of them are too big – and have to be broken down into smaller ones.

User story mapping

Let’s say you’ve written a number of really cool user stories that describe all the product functionality. And now you have a bunch of formalized features that you have to build – but it doesn’t give you any idea of where to start and how to proceed.

User story mapping is the process of arranging user stories in the form of a narrative that depicts the user journey as they interact with the product.

A story map allows you to visually organize backlog items in two dimensions: The horizontal one (a backbone) represents the user journey, and the vertical one denotes priority. In this structure, there’s also a place for epics, user personas, and so-called “nice to have” features that are under discussion.

A sample story map

A sample story map made in

Arranging user stories in story maps according to a scheduled release or sprint gives teams a better view of product goals and vision, allows you to discover missing items, facilitates backlog grooming, and inspires a productive conversation on how to bring more value.

User story estimation

We’ve been throwing in this estimation thing here and there – but what is it exactly? Well, any customer wants to know the duration and cost of the project in advance. And that prediction is what any development team always struggles with because there are just too many unknowns in software development, especially at the initial stages.

Estimate Software Development CostsPlayButton

Learn the skill of estimation from Frodo

Even though there are fans of the #NoEstimates movement (which emerged because someone was sick of always blowing the deadlines), most teams still make estimations. And one of the popular approaches involves using story points to measure the amount of effort required to complete one user story.

In a nutshell, story point estimations are made by playing planning poker, which is basically voting with cards that contain Fibonacci numbers, T-shirt sizes, or other relative measurement units. Once all the team members agree on the value, the estimate is set.

These story points are then presented to the customer and are also used to measure velocity, i.e., team productivity. If you want more information on story points and how they work, please check our dedicated post.

User story software

As we mentioned, originally, user stories were written on cards or sticky notes for the ease of managing them – and some teams still adhere to this tangible format. However, as the world digitizes, so do workflows, including project management ones.

Today, you can create and manage user stories in various digital tools that help visualize them and share them with stakeholders to support collaboration.

Most popular project management tools like Jira and Trello include user-story-related functionality, so if you use one of those to organize your activities, they work just fine.

managing user stories in trello

User stories in Trello

There are also more specialized tools to work with user stories. Here’s a list of some well-reviewed platforms compiled by The Product Manager.
  • Productboard — Best user story software for product feature prioritization.
  • Avion — Best user story software for complex backlogs.
  • FeatureMap — Best free user story software.
  • Featmap — Best open source user story software.
  • Visual Paradigm — Best for effective communication and collaboration.
Other practical tools worth mentioning are CardBoard, StoriesOnBoard, and Miro.

User story weaknesses and potential pitfalls

User stories are a handy instrument that can be applied to any development project, but they’re not perfect and have a few limitations that you have to be aware of.

Lack of understanding of the actual user's needs. If you write user stories as assumptions of what users want without conducting preliminary market research, you risk the failure of the project, as the product just won’t be something people need. So remember always to give an ear to actual end consumers.

Lack of context. User stories can sometimes be too vague or incomplete and definitely can’t be used for writing formal documentation. However, it’s their essence as they’re meant to be an invitation for discussion.

Omission of non-functional requirements. User stories are all about functional requirements. Non-functional requirements are nonetheless important and must be taken care of as well.

Lack of technical guidelines. User stories don’t tell developers how to build the feature (which can be a problem for inexperienced engineers). Instead, the team has to get creative, develop a shared vision, and write use cases and acceptance criteria that will serve as precise guidelines.

User stories help solve the problems of end users and refocus development teams from writing abstract code to fulfilling the needs of people who will actually interact with the product. They also encourage creativity and collaboration between various stakeholders. So consider our recommendations and implement user stories in your project to increase efficiency and create products that bring real value to your customers.

just an inspirational meme

Good luck with mastering user stories! Source: Allan Kelly