Refining How We Write User Stories

There are a variety of different project management approaches to writing the project’s to-do list. The two most common approaches I’ve seen in my career are tasks and user stories. In my experience, tasks are usually used in Kanban and user stories are more commonly used in SCRUM, but everyone runs projects according to their own flavor of agile. The project my team and I have been working on for the past few months is a SCRUM project, and in true agile fashion, we have been iterating on our approach to writing user stories.

We try as much as possible to write our user stories collaboratively. Having everyone engaged in this process helps us limit confusion as the sprint progresses, identify blockers more quickly, and seek clarity from design and product in real time. Because we’re writing stories as a group, we use a shared language and common approach when writing the stories. Our user stories follow the basic formula:

As a <user or role>, I can <action> [in order to <purpose>].

Before this project, I had never realized how many different ways there are to write user stories within this rather narrow formula. But there really are, and my team and I have tried many different approaches as we figure out what works for us.

Our initial approach was a common one you may be familiar with. We created one story for the backend (server) functionality and one for the frontend (client) functionality.

As a system, I can save an applicant’s general measurements.

As a user, I can view an applicant’s general measurements.

This approach is User Story 101 for making the stories smaller and more manageable. While I’ve seen this approach implemented successfully in other projects, it didn’t work for us. As a team, we like to be able to have demo-able code as often as possible, and we found that decoupling the frontend from the backend meant that we weren’t able to demo any work until we tackled the frontend story.

While the stories were small enough that they could be completed in a couple days, we kept inadvertently starting both stories and then keeping them in progress for the duration it took to complete both.

Because we kept doing our stories two at a time, we tried writing one story per feature.

As a user, I can view and edit an applicant’s hearing measurements.

This worked better for us. We always had a working feature to demo for our client, but it still wasn’t quite the right approach. Writing our stories this way resulted in pull requests (PRs) that were far too big. (A pull request is a version control feature that lets us notify the other engineers on our team that we’ve completed a feature and our code is ready to be reviewed before being merged and deployed.) It was too hard for us to be able to understand and identify side effects in the code when we tried to review PRs that large. There’s always a risk of unidentified side effects and bugs making it past a code review and being deployed, and that risk only increases in large PRs. We also found that these stories quickly grew too big to be completed in a couple days, and we were getting fatigued working on one feature for too long.

The latest iteration of our user stories is to write our stories more “functionally.” We’re struggling to come up with the right word to describe this approach but what we mean is to write them as the smallest testable slice that encapsulates all layers of a feature, from UI to database.

As a service rep, I can confirm an unsigned, watermarked contract with the applicant.

This approach has been working well for us so far. We always have demo-able features, our PRs are small enough to make our code reviews productive, and our stories stay small enough that we can finish them in a day or two. We do have to be careful when we write our stories this way that we don’t introduce too many story dependencies. Sometimes there are dependencies that can’t be avoided — you can’t display data before it exists in some form. But we’ve found that if we’re intentional about how we’re writing our stories, then we can limit blockers and maintain multiple parallel work streams so that our velocity doesn’t slow down.

User story writing is not an exact science and there’s always room for improvement. Until our team started actively iterating on how we write our stories, I had never realized the nuances of user story writing or how much of a difference successful story writing can make on a project’s velocity and deliverables

After a broad exploration in her schooling, including small engines, archaeology and punk rock, Mercedes finally found her niche in computer science. She earned her degree in computer science from DePaul University with a minor in American Sign Language Studies. After university, Mercedes dove head-first into consulting and has worked with a wide range of clients in industries such as healthcare, performing arts, beverage distribution, and hospitality. While her ASL skills are rusty, her passion for problem-solving and user-centered solutions never wanes.

Outside of work, she tries to unplug and enjoys fiber arts, particularly dyeing wool, spinning yarn, and crocheting.