How to write agile user stories: 7 guidelines

Fundamentally, agile user stories are short, simple tools to document a single action or intention desired by the targeted user to achieve a goal. The simplest user stories have a format, “As a user type or role, I want to action or intent so that reason or benefit” that answers at least three simple questions on who, what, and why the story is in the backlog queue.

As teams mature and organizations use agile across multiple teams and initiatives, agile user stories often take on a lot more definition and structure to ensure there is a shared understanding of the intent and underlying requirements.

Getting started with writing agile user stories

There are plenty of resources to help new product owners, business analysts, scrum masters, and technical leads to understand the basics of writing user stories. Some places to start include articles from Atlassian, FreeCodeCamp, Agile Modeling, and these 200 user story examples. One of the more complete writeups is in Alexander Cowan’s best agile user story. There are books on story writing, including User Story Mapping by Jeff Paton and Peter Economy and User Stories Applied by Mike Cohn. You can also take courses on story writing from Udemy, Learning Tree, VersionOne, and Lynda.

One fundamental principle first shared by Bill Wake is to invest in good stories. Invest stands for “independent, negotiable, valuable, estimable, small, and testable,” which make a good checklist for agile story writers. “An agile leader’s guide to writing user stories” is one article that explains how to apply invest principles.

The basics are relatively easy, yet I often hear and witness disconnects among stakeholders, product owners, developers, and testers around the quality of the requirements or whether a story is truly done. There are sometimes conflicting viewpoints on the level of detail required, where to fit in technical requirements, and what artifacts should be created with user stories.

With these questions in mind, here are seven beyond-the-basics guidelines on writing agile user stories.

1. Write stories for the audiences that will use them

Before writing stories, keep in mind that stories are meant to be read and understood by people participating in the development process with different needs and responsibilities. Story writers and contributors should keep the audience in mind and draft stories to address the collective needs:

• Product owners may not be the ones writing the stories, especially if your organization delegates this function to business analysts or if there are multiple people involved in story writing. Product owners want to make sure that the story fully captures the user needs and intent. They should read through the detailed acceptance criteria but don’t necessarily want to be bogged down with technical implementation details. Product owners should also understand how the story is aligned to the bigger picture, so they must take an active interest in how epics and features are defined and how stories are assigned to them.
• Stakeholders will not read the story details but will drill down from epics and read the story summary. If you have many stakeholders, consider using a descriptive format for summaries and moving the “As a user type or role” description to the start of the user story description.
• Technical leads are often the first person from the team to review stories, and they will study the requirements to see if a story is too big and should be split into multiple stories, or see if the story needs some upfront technical work to determine the best solution.
• The assignee is the individual responsible to review the details and report on progress at daily standup meetings. Assignees should be reviewing stories for dependencies that may become blocks during the sprint.
• Team members often review all stories to understand their assigned stories in the context of other stories assigned to the sprint.
• Testers determine if there are gaps or risks not identified in the acceptance criteria and then consider how best to implement them in automated testing frameworks.
• The team’s analyst, who may be a program manager or a member of the project management office, want stories fully labeled and categorized so that meaningful metrics can be pulled from the backlog.

2. Start with the user in mind

Although agile user stories may require many details, it’s very important to start with the user in mind. The story should be defining what action or intent the user wants to accomplish and why this addresses a need, a core value, or a goal derived from the experience.

For more complex applications, defining different user personas that illustrate needs, values, and usage patterns of different user types is an important discipline and can enhance story writing. In “10 tips for writing good user stories,” Roman Pichler suggests that “the persona goals help you discover the right stories. Ask yourself what functionality the product should provide to meet the goals of the personas.” Using personas to reinforce user goals provides a richer meaning of whya story is important and aids in prioritizing the backlog.

3. Answer why the story is important

Understanding, documenting, and discussing user needs or user persona goals is just one dimension around whythe product owner is prioritizing stories. The story should also provide business value, something that is hard to quantify but may be qualifiable at the story, feature, epic, or release level.  

Answering why can be important for the developers when they’re empowered to propose different implementation options. For example, a feature that improves the login experience for users may also benefit the business if the new experience also generates better customer data. A developer can reflect on this added business value and optimize the implementation for this goal even if the story’s acceptance criteria isn’t specific about this requirement.

4. Define acceptance criteria without prescribing a solution

The most significant discipline to focus on in story writing is in drafting acceptance criteria. These are often bulleted lists of short pass-or -fail statements that document requirements, constraints, metrics, and expectations. These acceptance criteria are often used in several ways:

• Technical leads and teams use them to estimate story points based on complexity and effort.
• Developers narrow down the implementation options to ones that meet acceptance criteria.
• Product owners may reduce scope or complexity of acceptance criteria to drive implementations with lower estimates.
• The assignee communicates blocks or issues meeting difficult criteria during standups.
• Quality assurance engineers use acceptance criteria to develop automated tests.
• The product owner reviews key criteria during the agile demo to ensure the story is done.

Writing acceptance criteria isn’t trivial. Acceptance criteria for acceptance criteria highlight some of the issues such as providing too many criteria, defining criteria that are too vague, or documenting complex criteria that can’t easily be verified. Some writers use acceptance criteria templates that define a structure for short, atomic, and testable criteria.

5. Use stories to define what and why; define tasks on how to implement

One of the critical mistakes I see teams make around story writing is to be verbose and specific around the implementation. These poorly written stories invest a lot of effort on describing howto implement often at the expense of describing whatthe user needs, why it addresses their goals, and where it drives business value.

There are a few reasons this might happen.

Inexperienced product owners may use stories to paint their implementation visions. In other words, they may be overly specifying user design and functional implementations instead of sharing the target user experience and benefits. Some product owners confuse their conceptualization of how something might work (the process by which they come to understand the requirements) with how it should work, accidentally turning an internal implementation example into an external implementation specification.

Other product owners may overstep their bounds by asking the team to “build me this.” That is one of my 20 bad behaviors of product owners, for which I have recommendations to product owners on collaborating with the team around solutions.

The other reason that stories may become cluttered with implementation details is that some teams and tech leads want this level of detail. Newly formed technical teams working to enhance existing applications may desire this level of detail until they better understand how the application works and fully comprehend user needs. Some distributed teams working with offshore developers or freelancers may also want to document the implementation details to ensure these members understand their responsibilities.

For such teams, the best thing to do is to link to implementation diagrams and document who is doing what and how as tasks linked to the story. Most agile management tools allow tasks or subtasks, and this level of detail is usually separated from the body of the story. A diagram in this post does a good job illustrating this important principle of using agile stories to break down user experiences and business processes and adding in tasks to define the implementation to individual pieces of work.

6. Tag your stories to drive analytics and practice improvements

Once stories are written, worked on, and completed, many teams look to capture metrics and perform analytics that can drive process improvement or used to make business cases for added investment.

Here are some examples:

• Label stories as technical debt to quantify the size of the debt, the percent of the team’s velocity used to address it, and the total debt completed with every release.
• Define functional and technical spike stories to drive experimentation and innovation, then report on where it’s having business impact.
• If your team is estimating agile user stories, ask the team to tag stories at the end of the sprint to signal whether they overestimated or underestimated to improve the accuracy of estimations.
• Use labels, components, and custom fields to aid searching the backlog for historical understandings or metrics. For example, knowing what stories impacted the APIs or what requirements led to the last functional improvements to a specific area of the application can be done when stories are tagged to functional and technical components.
• Tag stories collecting or processing sensitive information such as personally identifiable information (PII), e-commerce transactions, or industry regulated data such as HIPAA data to enable security and compliance reviews.
• Provide feedback to the product owner and team. Beyond marking a story done, a product owner could also provide feedback to the team such as acknowledging a great job. Similarly, the team can provide feedback to the product owner on the overall quality and interpretability of a user story.

7. Define agile story templates and style guides

Larger organizations working with multiple agile teams and product owners may want to draft standards and style guides for story writing. The consistency helps new product owners learn the writing skills faster and also improves team members efficiency in consuming the information.

Another reason to design story templates is that different types of products and applications lend themselves to different user story expressions and artifacts. Some examples:

• Business process stories may require links to workflow diagrams and also specify roles and permissions.
• Customer-facing applications stories should have links to wireframes and include performance criteria.
• API stories should document expected usage patterns and metrics.
• Business intelligence and data visualization stories should provide guidelines around what fields and information is needed for the requested analysis.

Templates help bridges the communication between teams and product owners on what to focus on when writing agile stories.

And isn’t that the point of agile stories? Agile story writing practices, guidelines, and principles are there to help teams know what’s important for users and for the business before considering how to implement.