28 min read

How to Write a Good User Story: with Examples & Templates

Writing requirements for a software project without a structure is a complete nightmare.

Tim Davidson
Tim Davidson

Writing requirements for a software project without a structure is a complete nightmare. Anyone who's worked on the development side of building a digital product knows that the biggest challenge isn't building the thing; it's knowing what to build.

Like everything else in software development, there's a scientific, systematic solution to this problem; the user story. A user story is a syntax of defining a requirement that's become the incumbent in software development because it both the business and developers understand what's required.

I've probably written more than 10,000 user stories. Still, whenever I take a break for a few months, I find myself browsing Google looking for examples of stories to see if I can strike up some inspiration of how to handle the trickier stuff (like authentication, project setup, design tasks, etc).

Every time I go looking, I end up on Reddit where the answers usually follow the theme of "no one would share actual user stories because they're legally protected" - which isn't true. It's just that user stories are boring, and no one has bothered to make Google index an article actually dedicated to story examples... until now :).

I'm sharing some examples of actual stories I've written recently, along with the behaviour-driven-development acceptance criteria my team uses to make sure that everyone understands the requirements and acts as a baseline for our automated testing.

Enjoying this post? Get more delivered to your inbox!

Enter your email to get a monthly round up of technology tips and news.

    We won't send you spam. Unsubscribe at any time.

    What is a user story? Our definition

    A user story is a vehicle for describing a system feature that follows a particular syntax. Even though it's technically possible to write a story without following this syntax, it wouldn't really be a proper user story.

    Here's the user story syntax:

    As some kind of user,
    I want to perform an action,
    so I can achieve an outcome.

    The idea behind this formula is to answer the biggest questions that developers have when they start building the feature.

    Which user are we working with? Is it an administrator, a user with restricted permissions, or someone who shouldn't even have access to the system?

    What does the user want to do? From the user's perspective, what are they trying to do? The important distinction here is the question isn't asking, "how should this feature work". Requirements should be agnostic of implementation suggestions.

    Why do they want this? Sometimes it's hard to understand how a feature should work simply by knowing what the user wants to do. Having the additional context to understand why they want to do something can let developers create a better-fitting solution.

    Pros of using stories

    User stories can feel tedious to write out, but they bring tangible benefits to the organisation and management of a software project.

    Remove assumption

    The biggest problems with application development projects usually come from making assumptions. Assumptions aren't limited to how the developer implements a feature; they're also made by the product owner (or client) on what's feasible.

    Define intent

    Without including the "so I can achieve an outcome" part of a user story, it's just a vague request that may not be the best way to achieve the outcome. Knowing the intention of a requirement helps get the product owner and development team on the same page.

    Standardised requirements

    Without a structure to stick to, requirements tend to take the easiest and sloppiest form. It's rarely consistent or detailed enough to figure out what needs to be done. Dealing with a large number of requirements that don't follow the same structure or approach is an absolute nightmare.

    Provides stakeholders with a way to communicate

    Stakeholders who are working with a development team rarely know how to think through their requirements fully or communicate them eloquently. User stories give them a concrete approach for explaining what they want.

    Cons of user stories

    User stories on their own don't really have "cons" or "disadvantages". The problems come from their implementation.

    They're easy to write poorly

    It's easy to accidentally write a user story the wrong way, so it doesn't communicate the business's need. For example:

    As a user,
    I want to implement a form plugin,
    So I can have a working form.

    From a developer's perspective, this doesn't get you any closer to understanding what the customer wants. The requirement is coloured with technical implementation details. If the best possible solution isn't to use a form then the development team can only achieve this requirement through a sub-optimal implementation.

    Customers often find themselves writing user stories, especially if they're going to market to get developer quotes. Without some understanding and practice, the requirements end up needing to be rewritten down the line.

    The format can feel repetitious and tedious

    A big application can require hundreds of user stories. If there are only one or two user types, then starting every single story with "As a user..." can feel

    Stories aren't complete without additional detail

    User stories are a conversation placeholder and aren't intended to have all the details required for a developer to start building a new feature. That part needs to be handled during a sprint planning session or technical review.

    To get the most out of our user stories, there needs to be well-defined conditions for completion and examples of how the story should work. This is where acceptance criteria and behaviour-driven development scenarios come in handy.

    What makes a good user story?

    A good user story doesn't necessarily need to follow the regular syntax, despite what a lot of die-hard agile project managers will argue.

    To be useful and complete, a good user story need to:

    • Covers a description of the feature to be built
    • Avoids any description of how the feature should be built (i.e. technology)
    • Explains the value to the end user
    • Has an outcome that can be measured and achieved
    • Consistent
    • They're testable

    A lot of teams, including ours, will start writing user stories in a slightly different format. However they're written, the story always needs to inform both parties of what's required and have a clear way of being achieved.

    Behaviour-driven development scenarios

    Before we get to the user story examples, it's worth talking through the other methodology we use to expand on the information available for the developers. User stories by design, are supposed to be concise and indicative. The developers and designers implementing the story will have plenty of questions that need to be answered.

    Behaviour-driven development is an approach of documenting requirements with examples. It follows a similar syntax to user stories:

    GIVEN some condition has been achieved
    WHEN a trigger event happens
    THEN a result will be achieved

    The idea is to document a few primary examples of how a feature (or user story) will be used. Providing actual examples not only acts as a great way to get everyone agreeing on how it should work, it also makes the product team think through the edge cases and creates tests that need to be passed for the feature to be considered complete.

    Agile user stories examples

    Finally, on to the actual examples. I've anonymised and sanitised these stories and scenarios a little to avoid making any of our clients upset.

    These stories would typically have a handful of acceptance criteria too for peripheral behaviours like confirmation or validation messaging. To avoid making them too hard to read through, I've left these out.


    Feature: Marking invoices complete.

    Story: As an administrator, I want to mark a job as invoiced, so it can be recorded and reconciled with accounting.

    Scenario 1: A job is completed and marked as invoiced

    GIVEN I'm logged in as an administrator
    AND I've completed a job
    WHEN I mark the job as invoiced
    THEN the UI will show the job as invoiced
    AND the job status will change to invoiced

    Scenario 2: A job is not complete and marked as invoiced

    GIVEN I'm logged in as an administrator
    AND a job has outstanding tasks
    WHEN I mark the job as invoiced
    THEN I will receive an error message that says, "Job can't be invoiced until all tasks are completed"


    Feature: Carpenter marks installation as complete

    Story: As a carpenter, when I've finished my installation, I want to mark it complete so everyone else on the team knows it's done.

    Scenario 1: The carpenter marks the job as complete, and job status changes

    GIVEN I'm logged in as a carpenter
    AND I've finished an installation
    WHEN I mark the job as complete
    THEN its status will change to "installed"

    Scenario 2: An administrator wants to know if a job has been installed yet

    GIVEN I'm logged in as an administrator
    AND I want to know if a job has been installed
    WHEN I open the job
    THEN I can see it's status is "installed"


    Feature: Staff unavailability

    Story: As an administrator, I want to see a list of upcoming days when the staff are unavailable, so I can resource and plan efficiently

    Scenario 1: An administrator wants to check who took holidays last month

    GIVEN I'm logged in as an administrator
    WHEN I view past staff unavailability
    THEN I can see a list of all staff holidays that are in the past

    Scenario 2: An administrator wants to check if a staff member has any upcoming holidays

    GIVEN I'm logged in as an administrator
    WHEN I view upcoming staff unavailability
    THEN I can see if a staff member has an upcoming holiday registered


    Feature: Calendar rolling date

    Story: As an administrator, I want to easily scroll up and down the calendar to see past and future dates, so I can plan my team's workload efficiently

    Scenario 1: An administrator wants to schedule a job 4 weeks in the future

    GIVEN I'm logged in as an administrator
    AND I want to schedule a job in 4 weeks time
    WHEN I scroll down the calendar
    THEN new weeks will display

    Scenrio 2: An administrator wants to check how many jobs were done last month

    GIVEN I'm logged in as an administrator
    AND I want to see what work was completed last month
    WHEN I scroll up on the calendar
    THEN I can see all the jobs that were scheduled and completed


    Feature: Discourse Single Sign On

    Story: As a user, I want to sign into Discourse using the same credentials I use for the app, so I can see my forum posts and comment history

    Scenario 1: A user wants to add a comment on the integrated Discourse forum

    GIVEN I'm logged in as a user
    AND I open the integrated Discourse forum
    WHEN I leave a comment
    THEN I will be successful without having to sign up for a new account

    Scenario 2: A user wants to view their forum post history through Discourse

    GIVEN I have an active application user account
    AND I've left comments on the forum in the past
    WHEN I log into Discourse
    THEN I can use the same credentials I use for the application
    AND I can see my forum comment history


    This is a decent cross-section of user stories and scenarios to get you inspiration moving.

    How to Write User Stories: Our Workflow

    The last thing to explain is our full process for building user stories. Achieving a full coverage of stories can be tricky and it's easy to miss things at the start of the project.

    At the start of every project, we run a Product Roadmapping session with our clients, consisting of a handful of 2-hour meetings. One of the goals of the sessions is to understand and document the major user workflows. A workflow is a user's steps to achieve their goal.

    Because workflows are less granular than stories, capturing them in totality is easier. Once you've got all the workflows, then you can move forward to breaking the workflow into the individual stories. Then the stories are decomposed into scenarios and acceptance criteria!

    Wrapping up

    Hopefully, this breakdown of how we write user stories, along with a handful of actual examples, has helped you on your journey. If you have questions, please leave a comment below, and we'll get back to you in a few business days.

    Written by
    Tim Davidson

    Tim Davidson

    Tim is the face of the company. When you want to kick off a new project, or an update on your existing project, Tim is your man!

    Read more on the subject

    Customer Experience (CX) - Why It Pays To Invest In CX

    Tim Davidson

    Is Mobile First Always The Best Approach?

    Patryk Michalski

    Digital Product Design Process

    Tim Davidson

    Don’t miss out on the latest stories!

    Sign up for my newsletter to receive the latest news from the blog, you’ll get pinged every few months with a digest from the tech world.

    Thank you for reaching out!