How do you create a good specification?

Filed under: BDD, Cucumber, Executable specification, Requirements, — Tags: Behaviour-Driven Development, Gherkin, Good specifications — Thomas Sundberg — 2017-02-26

A good specification is

An interesting question is "How do you create a good specification?" There are obviously a lot of different ways to end up with a good specification. You may be lucky and randomly end up with something good. There are, however, better ways than to rely on luck.

Behaviour-Driven development

One process of creating a nice, understandable, executable specifications is to use something refereed to as Behaviour-Driven development, BDD.

BDD follows a loosely defined process that includes these elements:

The process can be depicted as:


Discovering what the system needs to support is at the core of BDD. This can be done in many different ways.

One format that works well for some people is the Three Amigos, a term coined by George Dinwiddie. It can be described like this:

Time box the Three Amigos session to 25 minutes. Too long sessions are boring and not productive. Expect this time box to be too short the first times. But be aware that your goal is to limit the scope of the discussion so you can fit it in a short session. A long session probably means a large scope. A large scope may start with something well understood but it is likely that it will end in an area that isn't well understood yet. You might focus on speculations at the end and that isn't a good idea. It is better to allow the recent development feed into the discussion and therefore discuss well understood areas and concrete examples.

A low fidelity tool for driving the discussion is Example mapping. It is described by Matt Wynne and it only requires pen and paper.

Example mapping will help you find:


There are rules that we must implement. Every piece of software follows rules. Some are easy to understand, some are very complicated. Business rules are sometimes extremely complicated. As a product owner, you must understand and describe them. As a developer, you have to implement them. As a tester, you have to validate that the implementation is correct.

As professionals, we need every advantage we can find to be able to accomplish these tasks.

Concrete examples

Examples are used to check the rules. They must be concrete to be useful for confirming rules. Artificial examples are too easy to misunderstand. Concrete examples will help us discover what we don't know. They will make it easier to understand what areas we need to explore more to properly understand.


When exploring, it is likely that you will have questions that you don't know the answer for. It is not clear how the system should behave in a specific case. These questions used to be something called unknown unknowns. By exploring, they have now become known unknowns.

An unknown unknown is a risk that can't be addressed because you were not aware of its existence. But after this discovery, they have become something that is a known unknown and therefore a risk that can be addressed.

The conversation

The most important part of BDD is to discuss and talk about the system using examples. A good question is:

"Can you give me an example?"

Avoid implementation details

It is important to avoid talking about implementation details. One way of steering away from technical details is to imagine how the system would behave if there were no system but instead a lot of small Pixies running around and doing the work. What would they do to create the behavior we would like to see? Liz Keogh has a done a lot of work on the topic conversational patterns.


The examples found during the Three amigos session are documented using language called Gherkin. It can be done by the developer alone. It is, however, a great opportunity for the tester and developer to work together as a pair. Working in pairs is usually a much better way to do things compared to working alone. This is why pair programming is popular among many developers.

Features are stored as code and used during the development. The Gherkin files must therefore be version controlled.


The features documented using Gherkin are used for implementing steps in a programming language. The steps are used to drive the behavior. They will fail at the start of the implementation. The failing steps will pass when the actual implementation is properly implemented. These automated steps will now be used for regression and acceptance testing of the system.

The implementation usually follows the Red/Green/Refactor cycle of TDD.

As long as the desired behaviour still applies, executing the examples will act as a safe guard against mistakes during the life time of the system.

As a developer, I am grateful for anything that can save me from doing silly mistakes without noticing them. Silly mistakes are also known as bugs and every developer tend to create tons of them. Those without a safety net misses many of them.


You learn new things at each step in the process. This new knowledge feed into the other steps. That's why the image above is continuous. Each step has an arrow to the following. The production software feeds into the next discovery session. You have shipped something and got feedback from its use. This feedback will trigger what you should focus on next. Maybe there is a better way to do something?

Alternatives to BDD?

Are there other ways to do this? Yes. Anything where you have a conversation and talk about the desired behaviour is sufficient.

But following a step by step guide will help you get started. This is how most of us learn. We start by following rules strictly. The more we learn, the more we deviate from the strict rules. When we have learned a lot, it all depends.

If you don't know a lot about BDD, follow the format suggested by the Three Amigos and Example mapping. It will get you a very long way.


A tool for automating Gherkin is Cucumber. Using Cucumber will, however, not make you a BDD practitioner. The most important part of BDD is the discovery that you do discussing the desired behaviour.

Cucumber without discovery conversations are just as bad as writing a specification using a word processor. It will not give you the benefit of a deeper understanding from conversations. It will not help you find the unknown unknowns. They are only found when the assumptions someone had are being questioned. And sometimes not even then. They might be found when the assumptions are implemented and something strange or contradicting occurs.

Cucumber is available for most popular languages. There are Cucumber implementations for

Cucumber alone doesn't bring much value. If you only use Cucumber for test automation and never discuss the examples, it is probably better to ditch Cucumber and use a simpler unit testing framework. JUnit is a great candidate if you are in a Java shop.


A good specification is

One way of creating good specifications is to use Behaviour-Driven Development, BDD, and Gherkin.

The Three Amigos is a good format for discovery workshops and Example mapping is a good tool for driving the discussion during the discovery workshop. Example mapping will help you discovering the most important things, the unknown unknowns.

Cucumber is a BDD tool. But using Cucumber doesn't make you a BDD practitioner. BDD isn't about a tool. It is about creating examples and asking questions to to discover how the system should behave.


I would like to thank Malin Ekholm, Alex Bolboaca, and Paul Rayner for feedback.






Clean code
Continuous delivery
Continuous deployment
Continuous integration
Executable specification
Load testing
New developers
Pair programming
Public speaking
Software craftsmanship
Software development
Technical debt
Test automation
eXtreme Programming


Thomas Sundberg
Adrian Bolboaca



rss RSS