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

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, BBC.com 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 BBC.com 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.

Higher-arky

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:

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)

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: http://benmabey.com/2008/05/19/imperative-vs-declarative-scenarios-in-user-stories.html

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>

Where:

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)