< More blog posts

How to Write User Stories

February 21, 2019

What are user stories?

User stories largely take place of the traditional requirements documentation you see in more of a waterfall type environment. They are used as a way for the product team to understand the user persona and the ultimate goal, but leaves enough room for the product team to come up with the best solution based on their expertise.


A user story may be represented in various ways to ensure your team can deliver their best results. The main thing to take away from this post is that the process police won’t come find you if you’re not following these methods exactly. At the end of the day, the most important thing is that your team has enough autonomy to make their own decisions within the guardrails you and the rest of the team outline.


What type of work falls under ‘user stories’?


User stories can be used for almost any kind of product development; From design to development and even testing, it’s flexible enough to speak to any one of those individual groups. Traditionally, you’ll find that users stories cover the entire solution from beginning to end and include everything from design to testing, but we have found that it’s not always the most practical way to get the work done. So, we typically break out the design tasks from the development and testing tasks, as design typically leads in terms of progress.


Some other work that is inevitable, but may not fall under the structure of a user story for your team, could be referred to as ‘Chores,’ ‘Design Tasks,’ ‘Tests,’ etc. The separation of this work into various task ‘types’ allows for adjustment of your workflow based on the type (e.g., Chores, Design Tasks, etc.). This is largely specific to how you and your team function, but can be helpful when you have different work streams going on (e.g., working on validating a high-fidelity design prototype while the development team is working on features that have already been validated).


This section wouldn’t be complete without talking about how User Stories connect to the bigger picture. Most often, user stories are linked to larger initiatives called Epics. Epics are the highest-level of organization for agile tasks. Most often, Epics are features, whereas User Stories and other linked tasks are the tasks that have been broken down to complete that feature. However, different software solutions may even allow you to break things down more granularly, such as Epic -> Features -> Stories -> Sub-tasks.


Typically, Epics are what’s shared on a roadmap, and the stories and other related tasks are what determine how long it will take to complete that Epic (usually based on story points). An example of an epic could be ‘User Login’ and all user login based tasks/stories/chores could fall underneath that epic.


The Format of a Good User Story


It’s important that when you adopt user stories as part of your process that you go ‘all-in’ and ensure that they are structured in a way that allows your team to do their best work. User stories aren’t any good if they lack the necessary and/or relevant information the team needs to actually complete the work that your client and/or stakeholders are expecting.


Each user story I create typically involves the following parts:

  • Title
  • Overview
  • Acceptance Criteria
  • Reference & Considerations


Other elements that are involved in the process:

  • Testing Instructions (Provided by Developers)
  • Testing Verification Details (Provided by Test Engineers)


Now, let’s break down each of those parts.

Title


While agile based software has made all of our lives easier, I haven’t found software that makes it easy to scan for particular stories using a traditional story format method within the title field (e.g., As a x user, I want x, so that I can x). So, instead of including the ‘story’ part of the user story within the title field of a task, I typically create a shorthand so that it’s easier to find what you’re looking for at a moment’s notice. What this ultimately looks like is:


Title: Login | Forgot Password

Overview


Now that we have the title out of the way, it’s important to provide the team the context they need in order to come up with the best solution. This section should include just enough information for the team without prescribing a solution.


While some feel very strongly about following the traditional user story formula (e.g., As a regular user of product x, I need to be able to retrieve a new password in case I forget my password, so that I can log back into product x.’), I don’t think it’s 100% necessary to follow that exact format. What is important though, is that you stick with whatever format you choose to create consistency and predictability for the team on what they should expect for each user story. Using the example above, if I were to create this story I would probably just summarize a bit more to be something like:


Users need to be able to securely reset their password in the event that they forget their password.

Acceptance Criteria


Ah! Arguably the most important part of the user story. This is the part where things can become a little too prescriptive if you’re not careful. Remember, your goal is to communicate the needs to the team, without directly prescribing a solution (unless 100% necessary).

Here’s the thing about that though -- this requires that you to have a team of mature contributors. If you’re starting with a brand new product team, it might require you to be a little more prescriptive until trust has been gained amongst the team.


Using the basic example we’ve used throughout this article, the acceptance criteria I would include for this story would look something like this:


  • Users are able to securely reset their password
  • Once the user has reset their password, the user should be able to log back in using that new password


What’s important to note about the above criteria is that it (1) doesn’t prescribe if we should send an email, utilize secret questions, or utilize some other kind of (secure) authentication method to help the user reset their password or (2) it doesn’t say how this should look. Those details should be worked out among the product team so that they implement the best solution based on their expertise or the organization’s broader guidelines. Now, if you have some very specific requirements like ‘a user may only to request to reset their password two times in 60 minutes,’ that could be another acceptance criterion. Or, if this flow has already been created within the design prototype, you could include a criterion that states, ‘The forgot password flow should match the flow outlined within the prototype.’

Reference and Considerations


This section is great for keeping track of relevant information that isn’t necessarily requirements, but still important for the team to know (e.g., reusability will be key, as there are high-level business conversations around building this functionality out further). This section is also where I link all necessary support materials, such as the link to the prototype, necessary API documentation, etc.


Using the example above, assuming the designs do not exist, I would include the following:


  • Work with Designer X to determine the best possible user experience for the forgot password function
  • Please keep in mind that some regular users have 2FA enabled. They should have to enter their 2FA information before proceeding to reset their password.
  • Consider including some kind of captcha service to avoid people trying to use brute force to gain access.


Most often, I use this section to just include a link to the necessary screens in the prototype, as well as any ‘nice to have’ type of functionality.

Testing Instructions and Verification


Within our user stories, this typically isn’t part of the main story description, but instead included as links to documentation within specific repos and associated to a PR (pull request). The testing instructions give the other developer(s) reviewing a PR specifics on how they should verify that work, as well as the Test Engineer. Additionally, by separating the testing instructions out, it keeps the original story ‘pure’ while maintaining all relevant documentation in once place. On several of Crema’s product teams, the developers own adding the testing instructions. However, if you have specific flows you want to ensure get tested, I would encourage using your reference/considerations section for that.


Additionally, our Test Engineering team always adds a verification to each task tested. This includes relevant info such as what browser(s) they tested with, along with the version, as well verification that each piece of acceptance criteria passed or failed the tests. If anything fails, it goes back to ‘To Do’, but if it passes, it moves to ‘Done.’ This helps hold everyone accountable, but can also serve as quick documentation for DevOps teams if they must verify all tasks are tested before a release.

Who You Need to Involve in User Story Creation


Hands down, the best way to create user stories for your team is to involve them in the process. This is often done using a process called ‘Story Mapping.’ Story mapping is a way to visually map out the user journey, and then collaborate on the acceptance criteria to ensure no stone goes unturned and that your stories are written at the appropriate level of granularity. Not only is this process helpful to ensure you capture all the nitty gritty details and come up with the best solution, but it also holds everyone accountable, including your clients (as long as they’re involved). This helps ensure that surprise requirements don’t come up as frequently, or when they do, it’s more clear that it’s a brand new story.


This isn’t an article about how to run a Story Mapping ceremony though. You can find more information on the topic here.


So, running a story mapping ceremony for every single thing you and your product team works on may not be the most efficient process in all cases. While I certainly encourage the use of this for large feature sets (e.g., breaking down epics), sometimes you just need to create a few user stories without getting the entire team together. If this is the case, what I’ve found works best is to create the user story/stories and then run those by the team asynchronously or during one of your sprint kickoff ceremonies. Either path you choose, it’s important to get buy-in from your product team on them before proceeding.

Summary


Hopefully this article has shed some light on one of the ways Crema goes about writing its stories. If this process isn’t new to you, what are some ways that you’ve had success with the creation and implementation of user stories? Do you have any processes that have proven to be even better than what’s listed above? If so, leave a comment below! We’d love to hear from you!