Writing Effective User Stories

Learning Goals

  • Understand the different types of user stories
  • Understand the basic information included in each type of user story
  • Discover the guiding principles of writing effective user stories


Breaking down what you want to build is incredibly important when it comes to software. Too often, we decide that we’re going to build an application that does something specific without much upfront planning. This is where we can utilize stories to help us know what lego blocks we’ll need to build out and in what order so that we can accomplish our final goal. You will find that each team has a different way of writing stories. Despite these differences, there are a few core principles that can guide us.

Warmup - Turn and Talk

In small groups discuss what each of the following terms mean:

  • Persona
  • Features
  • User stories
  • Acceptance criteria
  • Chores
  • Bugs
  • Sprint

What is a user story?

Stories are placeholders for further conversations and documentation for context on conversations already had.

  • Instead of documenting every detail, they contain high level information
  • Stories should state the WHO, WHAT, and WHY not the HOW
    • Stories do not need to specify any information about how exactly an engineering team could implement the functionality in question.
  • Stories specify the reason for the functionality and what that functionality is.

Well Written User Stories

The INVEST model is a good way to evaluate if a story is well written.

  1. Independent - can be released without dependencies
  2. Negotiable - Ready for discussion and can be adapted based on team input.
  3. Valuable - Delivers value to the end user.
  4. Estimable - Dev team can estimate its relative complexity
  5. Small - As small as possible while still providing real user value
  6. Testable - contains the acceptable criteria that guides testing.

Discussion: How are you currently writing user stories?

In small groups, pull up a project board from a past project and discuss:

  1. What has been your approach to writing user stories.
  2. Do the user stories you’ve written in the past meet the INVEST criteria?

Questions to ask while writing user stories

  • Who is the persona you are focusing on? This should be defined
  • What is the goal of the persona for your story?
  • What should happen when the persona is successful in their goal?
  • What should happen when the person isn’t successful in their goal?
  • What is the acceptance criteria for your user story?

Elements of a User Story

  1. Title - short and descriptive includes the specific user persona
  2. Acceptance criteria - What determines if the story is complete
    • Given [Necessary Context], When [action], then [reaction].
    • As a __, When I visit __, I want to __, so that I can __.
    • if this statement includes a lot of ‘ands’ its probably an indication that the user story is too large
  3. Notes - additional information needed for the story
  4. Resources - wireframes, user flows, helpful links, etc.
  5. Labels - A way to group stories together

User story titles

The titles of your user stories should convey what is being worked on and what the user will be able to do once it has been accomplished. For example:

  • User can create a new account with the /sign_up endpoint
  • User can update user_profile information to an existing profile
  • Admin can update account information in their organization

User story details

Each story should be descriptive and outline a few things:

  • Is this a JSON endpoint? If so, what do the request and response formats look like? What happens when the user is unsuccessful?
  • Is this a frontend story? If so, what is the entire workflow of the user when attempting to accomplish the stories task?
  • Are there any additional resources that would make the story more clear? This could include wireframes, schema designs, etc.
  • The more information given in the story will allow you to start working without the need to ask too many questions.

Discussion: Bugs vs Chores

In small groups discuss:

  1. How are bugs and chores similar?
  2. How are they different?


  • Provide no new user value - typically not estimated
  • Usually impossible to estimate a bug, could take 30 secs or 30 days to resolve.

Elements of a Bug

  1. Title - short and descriptive
  2. Description - What is currently happening vs What should be happening
  3. Instructions to reproduce
  4. Resources - helpful information

If a bug is discovered in the middle of working on a feature, a new story should be created in order to track it. If you are busy working on a particular feature, another person on your team could take care of it in the meantime. If the bug blocks you from completing your current story, you should save your work, flip to a new branch, and begin working on fixing it. Once completed, you may return to your original story.


  • necessary but provides no direct, obvious value to the user
  • not estimated because, by themselves, they do not provide value to the user
  • can include refactoring, updating documentation, and a variety of project clean up

Elements of a chore

  1. Title - short and descriptive
  2. Description - Why it’s needed, is another story dependent on this task?
  3. Resources

Lesson Search Results

Showing top 10 results