Close
Glad You're Ready. Let's Get Started!

Let us know how we can contact you.

Thank you!

We'll respond shortly.

LABS
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.

  1. 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
    
  2. 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
    
  3. 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.

Comments
  1. 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.

  2. Janey says:

    Thank you – that does make sense now.

  3. 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)

  4. 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.

  5. Doug says:

    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.

  6. 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

  7. 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.

    Many thanks
    Jamie

  8. > 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.

  9. 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?

    Thanks.

  10. > 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.

  11. Lorie says:

    Awesome! Its really amazing article, I have got much clear idea about from this article.

  12. Todd Campopiano says:

    Hi Johnathan,

    Thanks for the article. However, I believe you are confusing the Gherkin format for writing/presenting Acceptance Criteria with the standard Agile User Story format.

    User Stories should generally be written as follows:

    “As a {USER TYPE/PERSONA,} I should be able to {WHAT} in order to {WHY / VALUE CONFERRED.}”

    Acceptance Criteria can be written/conveyed in a variety of ways depending on the nature/complexity of the requirements and the preferences of the team. In my experience, the multiple scenario Gherkin format is most useful to QA personnel when writing their test cases. However, the somewhat artificial nature of the format/syntax can make the Acceptance Criteria more difficult to read/understand by other team members (e.g., UX Designers).

    So I wouldn’t necessarily advocate that all Acceptance Criteria be written in the Gherkin format.

    Regards,
    Todd

  13. Hi,
    I was searching for a right methodology for sharing UX testing user stories.I am new testing and the terminologies so far i have understood what Genkin format is my QA team uses this format for user stories but when it comes to UX testing i am unsure if i have to follow a format or not.

Post a Comment

Your Information (Name required. Email address will not be displayed with comment.)

* Copy This Password *

* Type Or Paste Password Here *