Specification by example, my thoughts collected after workshop with Gojko Adzic

I had the pleasure of attending a two day workshop titled “From user stories to acceptance tests” with Gojko Adzic. The main topics that the workshop touched were specification by example and effect mapping.

In short: we want to use specification by examples in order to explore the domain language and decide what features are needed and why. We also want the single version of the truth that this living documentation will provide us. We want the tests that accompanies them to be confident about our system.

The long story:

Incremental vs iterative development

By making us build a game of black jack under time pressure, Gojko started off by illustrating the difference between incremental and iterative development. All of the groups in the exercise decided (without asking our customer) to design an algorithm for the back jack dealer. It seemed to us as a good start: a small piece that we would have the time to complete and deliver in the time given to us. When the customer at the end came with his acceptance tests and they all started with the “The player has a 10 and an Ace” we were all baffled. We hadn’t thought of the player and none of the tests passed. The customer had spent money and received nothing. Needless to say we were very embarrassed.

What we did was incremental development. We designed a component and wanted to later build more components to finally have a game. But the feedback loop in that case is very long. It takes a long time before the customer gets something he can try out. Gojko told us that it is common for development teams to basically say “We can’t really implement something useful for the customer in one iteration so we’ll do something now and then in x iterations we’ll have reached something he can try”.

The opposite approach is to focus on giving the customer a (basic) complete flow that we can receive feedback on right away. In our case, a simple game round with hard coded values would have been nice, just to see if it is what the customer had in mind.

Specification by examples and the benefits that come with them

Besides the benefits that come from the dialog with the customer, by working with specification by examples together with tests you will get a living documentation of the system. A single version of the truth about the system. When done right, this living documentation will be consistent, easy to read, easy to access. It will also be reliable, precise and comprehensive because of the tests.

To create good specifications it is important to keep the specifications and examples self explanatory. If there is need to explain it further then that information should be in the specification. It is also important to remember that the tests should be about the business domain and not about software design. For example, they shouldn’t be scripts (e.g. “Click”, “wait”). A script will tell us how something is tests but not what or why.

Effect mapping and business goals

On the second day we talked about effect mapping and how it can be used to achieve business goals. An effect map is a diagram with a business goal in the center. On the second level you will find the stake holders (users, marketing department, etc). These are the people that we identify by asking the question “Who can help us achieve our goal?”. On the next level we write down activities that the stake holders can do by answering “How can they do it?”.
An effect map will have elements of software design in it but will also contain other activities.

The next step will be to prioritize the map by trying to identify which goals are most likely to help us achieve our goal and to focus on those.

Gojko also talked about the benefits of keeping features within one business goal since it is easier to design features which are related.


The two days were inspiring and fun. I had trouble seeing how requirements, tests, product owners, developers, etc all could fit together and I feel that those pieces of the puzzle are better aligned now in my understanding of software development.

What was nice about the workshop was, among other things, the fact that Gojko bought examples from real businesses with him. He talked about their adoption processes and the mistakes that they had made. He also talked about their different constrains and how they had successfully worked around them.