Collaboratively specifying examples


Before developing a new feature, discussing behavioural examples helps teams to build the feature right first time. Issues and requirements gaps are detected and misunderstandings corrected before the team starts developing code and tests.

This collaborative discussion practice is a key aspect of the Specification by Example (SBE) and Behaviour Driven Development (BDD) approaches to software development.

Acceptance Criteria and Examples

When discussing a feature, it helps to describe the desired behaviour in general terms as acceptance criteria, along with specific examples.

For instance, an acceptance criterion might be that “All orders of $50 or over receive free shipping”. Examples might be “a $49.99 order has to pay for shipping” and “a $50.00 order has free shipping”.

It is important that each example relates to an acceptance criterion and that each acceptance criterion has corresponding examples.

Story mapping to many acceptance criteria mapping to many examples

By discussing examples, we often find gaps in acceptance criteria, or even missing stories.

Switching back and forth between the acceptance criteria and examples helps us discover gaps and gain a deeper understanding of the requirements.

Further details: Acceptance Criteria: Seeing the wood and some trees.

Structure / Anatomy of an Example

For each example, you should consider the context, action and outcome:

  • The context describes the preconditions that are in place for the example to take place. You should consider not only the application state, but also any relevant global conditions such as the day of week, or the location of the user.
  • The action describes the event you are testing.
  • The outcome describes the expected postconditions that should hold true.

During discussion we normally write these examples on a whiteboard or index cards. Rather than using lengthy sentences, we often find it convenient to use a shorthand form.

Tables and visualisations such as timelines or venn diagrams can quickly and concisely describe examples.

Exploring examples

To benefit from the discussion, the team need to explore examples that might not otherwise have been considered. Liz Keogh describes a couple of conversational patterns that help:

Context Questioning

Asking “Is there any other context which, when this event happens, will produce a different outcome?” helps us think of new scenarios.

Outcome Questioning

Asking “Given this context, when this event happens, is there another outcome that’s important? Something we missed, perhaps?” helps us find other things that our software should do.

Further details: Conversational Patterns in BDD.

Collaborative Specification Approaches

Involving a range of disciplines, including users, business analysts, developers and testers in the discussion is crucial to exploring examples from different angles, and gaining a shared understanding of the feature.

team discussing a spec

Common approaches to specifying collaboratively include:

  • Specification workshops - when starting out, having the whole team attend specification workshops acts as a useful introduction to the approach. Over time, some teams decide to continue with a whole-team approach, while others reduce the number of people in each session.

  • 3 Amigos - suggests a minimum of 3 functional roles; developer(s), tester(s) and business analyst or product owner.

  • Example mapping - uses index cards as a means to engage all team members collaboratively and visually map the story, acceptance criteria or rules, and examples.