A framework for modern User Stories

Jon Dobrowolski
Nov 24, 2014 · 5 min read

Though the User Story has entered its teenage years as a customer-focused software development mechanic, I still find a lot of confusion out there on how to structure modern Stories for success.

‘How much is too much detail?’ ‘Should it be as complete as a spec?’ There’s often an uneasiness from team members when they’re reviewing Stories they’ve authored with their team. Over the last 18 months, we’ve built up a lot of confidence in the method below. You’ll see how I write stories, what its done for our team, and how to make sure it works for yours.
So let’s start writing…

Begin with an example

Let’s get a feel for the structure with a sample behavior and its corresponding Story. Say you’re working on a site like Medium and you want to add a button to bookmark (save) articles (feel free to hit that button now and see how it works). Here’s how that story could look:

Let’s first take a look at the anatomy of this Story. Some things may look familiar to you…

User Story elements explained

Story Title

The title of the story uses the word ‘User’ when it relates to a user (vs. ‘Business’ if it was an analytics story for example) of the product and contains the word ‘Should’. I think this quote encapsulates the reasoning perfectly;

Every story title should include the word “should”. NEVER use the word “can”, which camouflages desired behavior. E.g. It’s unclear whether the story “User can delete comment” is a feature or a bug. “User should be able to delete comment” or “User should not be able to delete comment” are much clearer: the former is a feature, the latter a bug. Don’t make me guess. — J. Berger

Traditional User Story

While the original User Story format goes “As a <role>, I want <goal/desire> so that <benefit>” — we use ‘because’ to frame thinking around why this feature needs to exist and find that it sparks something (honesty) more effectively than ‘so that’. More on the genesis of the traditional User Story here.

User Scenario (the fun part)

The User Scenario is included not only to strengthen the traditional story, but also to imply behavior driven development / design (BDD). Writing your Story with BDD in mind creates a common language that is abstracted to accommodate business stakeholders, designers, developers and product managers. It’s simple but surprisingly powerful communication.

BDD relies on the use of a very specific (and small) vocabulary to minimize miscommunication and to ensure that everyone — the business, developers, testers, analysts and managers — are not only on the same page but using the same words. — behaviour-driven.org

This tenant of BDD is called a User Scenario or Given, When, Then statement…

Acceptance criteria should be written in terms of scenarios and implemented as classes: Given [initial context], when [event occurs], then [ensure some outcomes]Wikipedia

User Stories can contain multiple User Scenarios within them. If you see yourself writing a large number (>3 or so) at any time you’re probably discovering that the story should be broken down into smaller parts.


‘And’ can also be used to augment the User Scenario for semi-obvious changes in the system when the Scenario runs its course. You’ll want to use these with some caution as they can sometimes imply functionality that should be broken out into its own Story. See how we use the ‘And’ modifier below to attach instruction for a simple button state change.

Taking a look at how the ‘save’ function works on Medium, you see that the button’s state changes to indicate that it has been ‘saved’ successfully.


The ‘Info’ portion of the story is to provide any loose context, links to design files, copy needed, prototypes, additional stakeholders, etc. This is not included in the main Story as details can be variable. Stories can usually be estimated without light dependencies (final copy, final design, etc) if your team is in tight communication.

Why do it this way?

We use this style of scenario/Story writing to provide uniform structure to the Story. The goal behind a uniform User Story is for anyone on the team to be able to open a Story and know exactly what to expect. If you’ve ever sifted through a mess of unstructured information and then tried to get excited about building you know this lack of organization can cause frustration.

Tips for Success

First and foremost, “A user story is a placeholder and a promise to have a future conversation about the needed functionality.” — Your team needs to be in tight synchronization at all times. There is no one person that should be writing Stories. Product Management is all about setting priority but by no means are Product Managers the only people responsible for writing all the Stories. Your entire team should feel empowered to write a Story and pass it or a group of them around to the team for feedback.

Your User Stories, once completed, should serve as living documentation. I go back to Stories all the time to reference them in new Stories, get people the context they’re looking for, or remind myself how we did something. Treat your stories with respect now; they’ll pay dividends in the future.

Is this way of doing things right for your team? Maybe. The only way to really know is to try it out and solicit team feedback. We saw value in this format from day one, but we really loved it once we tuned the detail level in the Stories to work for our team.

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store