Secrets of Specification By Example

I was fortunate to attend Gojko Adzic’s Specification By Example training. Although I was familiar with the topic and the content of his book Specification By Example, I learn a lot. In this post, I will share insights around:

  1. How to build software right the first time.
  2. How to facilitate a specification workshop
  3. The secrets of great test automation

By the way you may have heard of Specification By Example through it’s other pseudonyms: Acceptance Test Driven Development, Story Testing, Feature Testing.

How to Build it Right the First Time (Zero Defects)

As illustrated in the diagram below, Gojko argues that the key problem in software development is a lack of shared understanding about what needs to be built. Language is imprecise and different assumptions lead to errors.

Specification By Example - Overview

A powerful way to justify spending time developing specifications is that it takes much less time to specify the behaviour of something than to build it. If something takes a long time to specify, this is a clue that it will also likely take a long time to implement it. The secret is to ask good questions and keep the examples rather than trying to create a written specification. It turns out these simple, small steps save a lot of time.

When everyone – domain experts, developers and testers – all have the same shared understanding, software will be built right the first time. This is the most essential property of Specification by Example – having a shared understanding.

Whether or not you create automated tests is somewhat of a secondary concern. It’s a good idea for sustainable development, but not required to deliver correct software.

And best of all is that everything here will work with a waterfall team as well as an Agile one.

How to Facilitate a Specification Workshop

A big part of the training (which I recommend) was participating in a simulated specification workshop so that we could see how they work and learn how to facilitate such them.

The most important thing is to call it a “Specification Workshop” and not talk about tests or test cases or automation so that it is easy for busy business people to attend.

The diagram below illustrates the key points:

  1. Cycle between large group and smaller groups
  2. Look for differences in language, models as well as where there was lot’s of discussion and conflict
  3. Seek to converge on a shared model using a ubiquitous language
  4. Conflict is a sign that there is a business decision to be made.

Specification By Example - Facilitation

Secrets of Good Test Automation

The final bits of wisdom came from reviewing real examples of test automation to determine how valuable they were.

Great specifications:

  1. Have a concise description
  2. Have a clear model
  3. Use business language
  4. Show a clear connection between inputs and outputs.

This is true whether or not we automate them. Automated specs need to be readable for business folks.

See diagram:

Specification By Example - Automation

The other key point is that the automation layer needs to be kept very simple – just wiring of the specification to the system under test (SUT).

How to Evaluate the Quality of Your Specification/Examples

There is a really simple test to see if you specification/examples are any good. But it’s scary.

Here is what you do:

  1. Hand the specification to someone and have them read it.
  2. Don’t say anything.
  3. Don’t say anything. (This is the most important step, so I am repeating it).
  4. Write down questions they ask – these are clues of how the spec can be improved.
  5. Looks for the “ah-ha” moment when they understand. If you don’t see this, then there’s something missing.


I am deeply grateful to Gojko Adzic for delivering such an interesting and engaging training. He is a master storyteller and has an immense collection of real-world examples. If you get the chance, I highly recommend this training.

I would also like to thank the Toronto Agile Community for brining Gojko Adzic here as part of Agile Tour Toronto.

Thanks also to my classmates who made our time together challenging and fun. And especially to Paul Carvalho for reminding me what testing expertise really looks like.

Print Friendly
Tagged with:
, , , ,

Find Content

Adoption Agile Agile2009 Agile Failure Agile in the Large Agile Tour Toronto Change Artist Christine Day Coaching Communication Container Craftsmanship Creativity Empathy Facilitation Fear Games and Simulations Hierarchy Kanban Kotter Leadership Lean Management Observing Organizational Change Organizational Culture People Personal Growth Production Product Strategy Project Management Red Pill Safety Scrum Strategic Play Teamwork Technical Practices Training Training from the Back of the Room Transformation Transition Trust VAST Vulnerability XP


  1. Really good stuff and many thanks for sharing. I hope Gojko will come to Sydney and do workshop here some day. I do have a question though. what do you mean by “Cycle between large group and smaller groups”. Can you elaborate a little bit on this? Thanks again.

    • Hi Frank,

      Glad you found this useful.

      Good question. We break into small groups that explore the SAME examples. The purpose of small group time is to develop examples and notice problems. This may only be 10 to 20 minutes.

      As facilitator, we come back to the large group once there are some interesting things to discuss. Learning comes from things that are different between groups: models, language, what examples work best, etc. In large group, we arrive at consensus around these things so that we can go back to small groups to keep exploring the problem domain.

      – Michael

  2. Hi,

    I was at a specification workshop some time ago and your summary is concise and excellent. Thanks for reminding me! Just one thing stumps me every time – Should managers be at the specification workshop for the business decisions or not? You see, if the managers are there, the meeting becomes more complicated to set up and move. If they aren’t there, key decisions aren’t made and too many things are shelved. Any ideas you have would be welcome!

  3. Hi Danielle, you have outlined the trade-offs really well.

    I am not an expert, but some of the thoughts that come to mind are to do it both ways and see what works better in your context. Another possibility is to make the decision of including managers based on expectations around need for input – so “safe” features v.s. ones which are likely to trigger business decisions. – Michael


Submit a Comment

Your email address will not be published. Required fields are marked *