The importance of Specification By Example

James Marsh

5 minute read

You may recognise this situation...

You’re sitting in the first sprint demo of your new website, but something isn’t quite right. Three months ago you signed off the requirements with your Business Analyst and gave the project the green light to proceed. But sitting in your first sprint, you realise that what you’re seeing doesn’t match what you thought you’d see.

"Why is the customer being shown a discount here? They haven’t spent enough to be eligible for that yet” you ask.

The delivery team explains that the requirements document describes two competing business requirements for discounts: if you spend more than £100 then you are given a 5% discount. Students get a 10% discount.

Yes, students would get the 10% discount here, but only when they’re spending more than £100”, you explain. “And last week we changed student discount to 20% so this needs updating”.

Oh. We thought the requirement was that students always get a 10% discount, no matter how much they spend”, replies the project manager. “That’s going to take a chunk out of the next sprint to rewind.”

The requirements document that you rely on to steer development is now out of date, and has been misinterpreted by the delivery team - and it’s only the first sprint.

When Friday starts a new project, we use a technique known as Specification By Example (SBE) to avoid situations like this. SBE is a way of capturing acceptance criteria (the rules by which a specific feature is judged to work as intended) that uses realistic content and data examples expressed in simple language, rather than abstract technical statements. It encourages the closest possible collaboration between business owners and those delivering the product.

We use either high fidelity visual designs or wireframes as a basis for SBE, and define the desired behaviours across all user scenarios and edge cases. It’s normally conducted after the user stories are mapped out, but before features are assigned points reflecting their relative complexity:

Specification by Example process

We use SBE at Friday because it enables straightforward conversations with all stakeholders to discuss, create and set clear requirements. It means problems can be highlighted earlier, and fixed more efficiently.

The process usually involves stakeholders from the client organisation such as a product owner or BA, and members of the Friday team working on the project; a delivery manager, developers, QA’s, strategists and designers. We tend to work as a single, blended team – with the close collaboration bringing several benefits:

  1. Open communication

    All stakeholders are involved and the open discussion helps tease out potential problems early on.

  2. Clarity of understanding

    Real life examples expressed in simple terms maps out a simple vision of “the thing we’re building and why it will be successful.”

  3. Less assumption

    Working through examples as a team forces everyone involves to truly define what’s needed at a granular level.

  4. Ease of iteration

    The process enables continual updates via JIRA as the project progresses.

Kate Warner, Head of QA at Friday, describes the importance of SBE’s contribution to our modern engineering methodologies:

From a QA perspective, SBE is a key step in our practice that allows us to define our test scenarios, get a feel for the importance and the end user experience of given features, and to agree a common language to describe what we are delivering. In an agile and fast paced environment it is a very effective way of providing a framework for delivering fit-for-purpose software.

At Friday, we transform the customer experience by digitising core products and services at speed. SBE is a critical component in our being able to rapidly deliver digital solutions that work.

If you want to hear more about Specification By Example or any of our methods, then please do get in touch at

James Marsh

Lead QA

Friday is now part of PA Consulting