The Elements of Style for User Stories and Scenarios (BDD)

The core content of this post was forged in the fire of an intense agile project that was the conception and creation of the international edition of the BBC Homepage for

The project team was assembled and some engineers had worked on the original domestic homepage but this was a complete redesign and rewrite, and of course the team was under commercial pressure to deliver ASAP (yes, is a commercial enterprise).

So the scene is set. I had joined the department fairly recently and was leading the Business Analysis. By this I had many years of experience establishing requirements for projects large and small, agile and waterfall, and lots in between. Mike Cohn’s User Stories Applied had served me well on recent agile projects but my skills were about to step up a gear thanks to Julian Everett who was at that time the Chief Architect for and is a truly inspirational guy. He turned me on to BBD developed by Dan North. At which point we rapidly adopted BDD as the way forward for the BBC Homepage project. We rapidly tooled-up with Cucumber, Ruby Mine, Capybara and Selenium Webdriver. It truly was a cross-functional team effort uniting testers, developers, UX, designers, stakeholders, business analyst, etc behind a common visions for the product but also behind this new development approach. We had ubiquitous language coming out of our ears… and mouths, with lively discussions along the way.

It’s a Style Thing

Like programming itself, you can look at writing requirements as art, science, engineering or craft. Choose your own perspective. The bottom line for me is that writing requirements comes down to good style. I am talking about the documentation of established requirements here. Requirements analysis (including problem decomposition) and validation have already occurred or have to a partial degree. The form in which requirements are expressed during analysis, especially when uncertainty is high is the fuel for a separate post.

Style can be distilled into some simple rules, or acceptance criteria for the very user stories and acceptance criteria themselves. Here we go.


Dan North refers to it as “outside-in”. In my pre-grad Software  Engineering days we called it “top-down”. In any case, we should think hierarchically. The very definition of analysis is “the separation of an intellectual or material whole into its constituent parts for individual study”. So where do we begin? At the very top or the outer most perimeter and from there work our way down or in:

  1. Product Business Case
    justification and high-level scope > expressed as User Stories
  2. KPIs and Objectives
    > expressed as User Stories
  3. Feature
    = feature level user story as an MMF (Minimal Marketable Feature)(maps to a Cucumber feature file)
    > expressed as a User Story
  4. User Story”
    = user stories breaking down the MMF into sub-features (from a user perspective of course)
  5. Scenario
    = acceptance criteria for user stories at level 4

You may have your own variations on this theme. Levels 3 & 5 form the structure of BDD as implemented in Cucumber’s language, Gherkin. We found that level-4 user stories provided finer grained grouping of Scenarios (although these were commented out and not executable). We also used Cucumber Tags to tie related scenarios together in “themes”. There are many ways to slice-and-dice your problem domain and good, reasoned choices here make a big difference. This is the ‘architecture’ of your requirements.

Since levels 1 – 4 are all expressed as User Stories, this means that the purpose and value is stated in the “In order to…” line of each user story. The purpose should cascade and therefore purpose at level 4 should be traceable back up the hierarchy of user stories through level 3 to level 2. The Business Case of course states the business purpose of the whole product. If value at lower level does not fall under the purpose at a higher level then by definition it is out of scope.

The act of hierarchical decomposition itself should be prioritised according to business value, technical risk, etc. This may drive the order of further Business Analysis and ultimately the build and delivery, i.e. Sprints.

The above levels are augmented by the following to provide a complete and unambiguous view of the product to be developed:

  • Vocabulary – defines the terms used throughout the product definition and build. This page also defines the BDD @Tags used to relate scenarios under common themes.
  • Designs
  • Style Guide
  • Plus any other visualisations that provide insights into the product being developed.

Having set the scene and set the context, the remainder of this post focuses on the elements of style of writing good user stories and acceptance criteria, regardless of the particular development methodology.

User Stories

  • the story should be small enough to fit in an iteration (break epics down into user stories)
  • always break the story out along end user value lines rather than along technical lines
  • always make assumptions explicit
  • cucumber uses the Feature level user stories only and pools all scenarios beneath the feature (which may be beneath user stories belonging to the feature)
Anatomy of a User Story:
  • User Story: <Title>
  • In order to <benefit>
  • As <role>
  • I want <outcome>


User Story: <Title>
  • must be unique (for Cucumber, within the Feature-level user story)
  • should describe an activity
  • best expressed as subject-verb-noun phrase, e.g. “Account Holder withdraws cash”
  • acts as a short-hand identifier for the user story (there are no numerical IDs)
In order to <benefit>
  • state the purpose / intended outcome; the reason this is of value to the user
  • should be quantifiable where possible (benefits are tangible or intangible)
  • technique: “pop the why stack”; “The Five Whys” (Caution: use selectively)
  • should be clear why this is one of: (a) revenue generating, (b) revenue protecting, (c) cost saving
As <role>
  • should be an end-user
  • if an internal end-user, e.g. an editor of content, then:
    • this should be a specific role; should not be a person’s name, use their role title in relation to the product; this may be different to their job title
    • should be the most directly ‘accountable’ role; the ‘A’ in ARCI/RACI stakeholder chart
    • should add context if multiple people with same role, e.g. “WW Homepage Editor”, “Travel site Editor”; should be explicitly stated and not relied on in context of the project
    • will sign-off the user story as complete and representative of their specific requirement (via its Scenarios as acceptance criteria – see below)
I want <feature>
  • may be a feature level (MMF) or sub-feature
  • ideally stated as a specific observable outcome (Scenarios add more detail)
  • should avoid specifying the solution where possible as this information should inform solution design not dictate it; an exception is if is it known that only a very specific solution will be accepted
  • expressed as an active verb-noun (or subject-verb-object) phrase

Scenarios (Acceptance Criteria)

  • scenarios should read like the user ‘naturally’ speaking rather than a technical person, e.g. avoid technically structured statements and parameterised statements which sound unnatural
  • scenarios should describe an example situation that needs to be handled, i.e. a “Scenario”, as it says on the tin; this is sometimes overlooked
  • striking the right balance of abstraction is a key consideration and act of judgement; in general, abstract is better, i.e. should not be implementation dependent. An exception of course is where an implementation detail is the actual outcome required
  • related to abstraction: Declarative versus imperative; good to aim more towards the declarative end of the spectrum; being too imperative leads to scenarios that are verbose, noisy, brittle to changes and are therfore a challenge to manage. They also risk alienating stakeholders which is the exact opposite of what you want and what is at the heart of BDD. Here’s an excellent article on this subject:
  • state the obvious and state the assumptions; these often overlap
  • cover the edge cases, the “Unhappy Scenarios” as well as the default, happy scnenarios
  • some scenarios are best described as a sequence: given <some context> when <I do something> then <this happens> when <I do another thing> then <this new thing happens> and so on
  • scenarios as “specifications” not test scripts: do not approach as traditional test scripts with program flow and conditional logic

Anatomy of a Scenario:

  • Scenario: <Title> 
  • Given <context> 
  • When <event> 
  • Then <outcome>

Scenario: <Title>

  • must be unique within the product scope
    (enforced at Feature-level user story within Cucumber)
  • the scenario title should say what’s different (from other Scenarios)
  • should be able describe how scenarios differ using only the title
  • acts as a short-hand identifier for the scenario (there are no numerical IDs)
Given <context>
  • some initial context (the givens)
  • use And… to define multiple facts about the context
  • should define all of, and no more than, the required context
When <event>
  • some specific event such as a user action
Then <outcome>
  • the outcome that needs to be ensured
  • use And… to define multiple outcomes

Happy user story & scenario writing!


Leave a Reply

Your email address will not be published. Required fields are marked *