How to write Well-Formed User Stories

Writing Well-Formed User Stories

Convention Over Configuration is one of core principles of the Rails approach to software development, and delivers enormous value.

Convention Over Configuration – means that Rails makes assumptions about what you want to do and how you’re going to do it, rather than requiring you to specify every little thing…

Oddly, we tend not to apply the same perspective to project planning: on almost every project, the team re-invents the wheel of “how should we write and format our stories?”. I’ve worked closely with the Product team on about a dozen projects in the past few years, and rigorous story-writing is one of the most common areas for low-cost, high-gain improvement. I encourage every team to adopt (or at least consider) these techniques.

Write every story in Gherkin. I don’t care whether or not you use cucumber: use Gherkin. Which is to say, every story should be in “Given / When / Then” form. This is the cheapest and easiest way to apply Convention Over Configuration to your user stories, and can have a HUGE benefit for your team.

Scenario: User adds item to cart
Given I'm a logged-in User
When I go to the Item page
And I click "Add item to cart"
Then the quantity of items in my cart should go up
And my subtotal should increment
And the warehouse inventory should decrement

Every feature story should include an “As a / I want to / Because…” block, which illustrates the motivation behind a story. Compelling the product team to specify the motivation behind a story help illuminate what exactly the requirement is, as well as providing guidance to the developers. Some people prefer “So That…” instead of “Because“, but in most cases “Because” helps drive out motivation—the Final Cause—whereas “So that” may only drive out the Effective Cause, which is less useful for understanding the story. (Thanks to Sam Coward for this insight.)

Feature: Shopping Cart
As a Shopper
I want to put items in my shopping cart
Because I want to manage items before I check out

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.

When a story feels a little fishy, check that these bases are covered. If any are missing, fix then before you do anything else. The answer will often be driven out in the process of working the story into Well Formed shape.

Benefits

Well Formed stories truly drive out the feature from the user’s perspective; this catches 80% of weird edge cases while the whole team is together, in context, and in planning mode, instead of having to interrupt-drive the PM. Well Formed stories make it impossible to camouflage large stories as small stories by elision. Because the story has to be written out step-by-step, all the complexity might otherwise be hidden is forced out into the open. And when you find yourself with conditionals or switches? That’s a new scenario! Now all stories are forced into roughly the same size. Another side-effect is that once one story ~= one scenario, the amount of work to be done can be roughly gauged spatially, by looking at how much of your wall is covered by index cards. For bonus points, use the story title as your git commit, e.g. the story “User should be able to recommend a product” becomes the git commit “User is able to recommend a product”, and your git log tells the narrative of your project.

How did this start?

Once apon a time, J (the anchor) made N (a very bright, technical Product Manager) write stories in Gherkin. Most stories weren’t 100% ready to be pasted into cucumber, but it usually didn’t take too much work to get them there. The team would discuss in IPM, and then devs could copy-and-paste stories right into Cucumber. This doesn’t work for every PM, but even in the worst case, teams with less than tech-savvy PMs see real benefits from writing their stories at the right level of granularity. Once I was exposed to a team where we wrote Gherkin all the time, anything else felt like broken process.

UPDATE: To be clear, the opinions in this article are my own, and do not reflect anything close to consensus or standard practice on the part of Pivotal. Some Pivots will agree with this position, while many others will not.

UPDATE 3/17: Added a brief introduction elaborating on how Well-Formed Stories help bring principles of Convention Over Configuration to story-writing.

12 Comments

Janey says:

Ok, now I’m confused again… please help! You say: “Write every story in Gherkin” i.e. Given/When/Then… and “Every feature story should include an “As a/I want to/Because…” block… So are you saying there are TWO kinds of user stories now? A User Story and a Feature Story? – OR – do they get combined? If so, please show us. If not, what’s the difference between a User Story and a Feature Story? Also, is a Scenario the same thing as a User Story? Thanks for the clarification.

August 2, 2013 at 9:06 pm

Jonathan Berger says:

Good questions, thanks! To clarify:

> what’s the difference between a User Story and a Feature Story? Also, is a Scenario the same thing as a User Story?

I don’t see much of a meaningful distinction between “User Story” and “Feature Story”. Usually we just use the term “Story”.

As a Shopper
I want to put items in my shopping cart
Because I want to manage items before I check out

Given I’m a logged-in User
When I go to the Item page
And I click “Add item to cart”
Then the quantity of items in my cart should go up
And my subtotal should increment
And the warehouse inventory should decrement

—

> Also, is a Scenario the same thing as a User Story?

Calling out “Feature” and “Scenario” is more proper Gherkin, but I rarely find it useful enough to include. The exception is when a Product Owner and I are talking through a story, and we start to find switches—the words “if” and “or” and “unless” are good hints that you’ve got more that one story going—and then we might start throwing Scenarios in. E.g, if the stakeholder continued telling us about the shopping cart, and said “…unless we’re out of stock, in which case we should notify the shopper, add an item request to our merchandiser, and set up an email-alert for the shopper when the item comes back in stock.”, then we’d break out Scenarios:

– Scenario: Item is in stock
– Scenario: Item is out of stock

We might subsequently break each scenario into its own story, at the discretion of the development team.

Does that make sense?

August 3, 2013 at 10:56 am

Janey says:

Thank you – that does make sense now.

August 3, 2013 at 5:17 pm

Nic Werner says:

I use this schema, and I think it’s great to educate client PMs to have this discipline. But I think it also depends on the team culture, and their maturity. I have been on Pivotal projects where the team was high-performing and I was told (as PM) that they didn’t want this level of detail(!) in their projects – just a short description and the pair working on it would come up to me and ask for more detail.

That being said, I prefer to have fuller information in the story because it 1) helps for acceptance 2) assists the QA team (if there is an external QA unit)

September 11, 2013 at 6:13 pm

Jonathan Berger says:

> I prefer to have fuller information in the story because it 1) helps for acceptance 2) assists the QA team (if there is an external QA unit)

Me too. In my experience, this information *has* to be specified, the only question is when: during planning, when everyone’s got context, or during interrupt-time when the pair has their head somewhere else.

> I use this schema…But I think it also depends on the team culture, and their maturity.

This won’t work for every team, but 1) it will work for many (most?) teams, and 2) having a standard template to start from prevents teams from re-inventing the story-writing wheel on every new project. That’s a huge win.

we’re trying out something very similar. i echo nic werner’s sentiment that the level of detail is too fine on either side sometimes. so the challenge becomes knowing which features need more or less story grains.

to address this, i am trying out a precursor step of “product story” — which is really just a list of modules, features, and use cases. we couple this with a screen flow document and then have a series of PM/dev sessions to generate a list of stories.

December 20, 2013 at 11:39 am

gumaflux says:

Great article Jonathan, great response to Janeys question it provides a top little pattern for our story writing. I showed this to my co-founder and she got it spot on, something I have tried to “explain” in bizarre worse ways.

Thanks excellent

February 28, 2014 at 5:06 am

Jamie Hough says:

Hi there,

This is an excellent post and hope its still active as I have a number of questions regarding the example outlined by Jonathan.

Title: User should be able to add item to cart.

As a Shopper
I want to put items in my shopping cart
Because I want to manage items before I check out

Given I’m a logged-in User
When I go to the Item page
And I click “Add item to cart”
Then the quantity of items in my cart should go up
And my subtotal should increment
And the warehouse inventory should decrement

—

Question:
1. Should this story include the item details that are displayed in the cart? e.g. each item in the cart should display item name, item description, price etc.
2. What about add item rules (e.g. the cart can only hold 20 items for example). Would this be a new story or would you add this detail in the story?
3. Would you add another story for non logged in user’s adding items to a cart?
4. Would you add another story for removing items from cart.

> 1. Should this story include the item details that are displayed in the cart? e.g. each item in the cart should display item name, item description, price etc.

It usually depends on what’s comfortable for the team. Some teams find it’s helpful to specify this stuff in the story, others might just convey basic details in mockups or wireframes. I’ve seen plenty of stories with lines like

When I go to the Item page
Then I should see the Item Name
And I should see the Item Description
And I should see the Item Price

> 2. What about add item rules (e.g. the cart can only hold 20 items for example). Would this be a new story or would you add this detail in the story?

“Cart can only hold 20 items” sounds like a new story to me. Generally, a user story should be as small as possible, while still having user-facing value. “Guest user should be able to add items to cart” and “User should be able to remove items from cart” would probably also be their own stories. The Gherkin would be an opportunity to think through the user flow: “Given I’m a Guest, when I add an item, and I try to click “go to checkout”, Then I should be prompted to login” etc.

March 4, 2014 at 2:42 pm

Alex Bunardzic says:

I like your convention-over-configuration angle. One question:

We tend to further break each user story into up to five-six scenarios. This is following Dan North’s suggestions (http://dannorth.net/whats-in-a-story/) where he says that scenario titles, when lined up side by side, should point out only the differences between them. You, on the other hand, seem to be implying that story usually means a single scenario (a one-to-one relationship). Or have I misunderstood you?

> We tend to further break each user story into up to five-six scenarios…You…seem to be implying that story usually means a single scenario (a one-to-one relationship).

It depends on the size of the feature and the way developers prefer organizing their tests. Some teams prefer atomic tests (one scenario per file, which can lead to lots of files), while others prefer grouping multiple scenarios into a single test (which can lead to “which feature file should I put this scenario in?” and “how do I know which scenarios should induce a new feature file?”). Either approach works as long as the team is communicating.

Jonathan Berger is a designer, developer and technologist who has been active in the NYC technology scene since around 2005, helping to organize events like the Agile Experience Design Meetup, the Pivotal Labs Tech Talk series in NY, Startup Weekend, Barcamp, Fashioncamp, and IgniteNYC. He spends his days building software with Pivotal Labs and his nights and weekends working on Market Publique. Prior to that, he earned a Bachelors in Philosophy at Vassar College and a Masters in Media Studies at the New School(where he also spent quite a bit of time at Parson’s Design + Technology program). He has worked as a designer, developer, video editor, animator, and technology consultant for institutions as diverse as Eyebeam, MTV Networks, Yahoo!, Ogilvy, and the American Museum of Natural History.
He speaks about startups and technology at events like the Future of Web Design, O’Reilly’s Web 2.0 Expo, New York Tech Meetup, Fashion 2.0 Startup Showcase, Startup Weekend, North Brooklyn Breakfast Club, The Product Group, and others.
He makes it a point of honor to include Comic Sans in every design project.
Find him on twitter, github, flickr, etc. as @jonathanpberger.