• en | es

Learning Specification By Example from Gojko Adzic

I recently completed my Apprentice-craftsmen Programme at Codurance and as part of my graduation, I wanted to take a training course on something that had been on my ‘to do’ list for far too long! Skills Matter were hosting Gojko Adzic’s “Specification by Example: From User Stories to Acceptance Test" training course … taught by Gojko himself! It’s not every day that you get to meet Gojko - which is why I spent the best part of two weeks, prior to attending, reading and internalising two of his books: “Bridging the Communication Gap” and “Specification by Example. How successful teams deliver the right Software”. This helped me to not only make sure that I got the most out of the course (i.e. what questions to ask) but also to set some goals for the 2-days. After giving this some thought, these ended up being:

  • Put the theory into practice with the hands-on exercises.
  • Learn something that I couldn't find in Gojko's books.
  • Cement at least one thing that helps me write good specifications.

I'm glad to say that each of these goals were achieved, and more! Here’s what I learned.

2-day hands-on experience

Before attending Gojko's course, I believed it was impossible to run a session without showing boring PowerPoint presentations, but he managed to avoid them! In fact, his course is a 2-day hands-on experience which is a very effective way to show what you can get by Specification By Example (SBE) and when to use it.

To get us across those essential concepts, Gojko has created two collaborative exercises, which aim to simulate what happens when there is a lack of domain knowledge and the team is under time pressure. These are two typical situations in larger organisations when the team is working on a system that is a piece of a larger puzzle that nobody fully understands.

Learning something new

Thanks to the collaborative exercises, I went beyond the theory explained in the books, and I learn how to write good specifications by experiencing how to run and facilitate a Specification By Example Workshop. I learnt how to discover the right questions to ask by collaboratively visualising team's and stakeholders' understanding through real examples. Here are few guidelines to follow:

  • Given the acceptance criteria, ask people to write down the simplest possible examples of what we want to test. This is important as it helps to actually start the conversation.
  • Let the example structure emerge so that it's possible to identify knowledge gaps and different levels of understanding and needs. In the example structure, you’ll discover preconditions and outcomes. Sound obvious, but this can help to avoid an incorrect transfer of domain knowledge.
  • Identify modelling problems (how you name key concepts in your domain) and solve them by building up a common language (Ubiquitous Language). Again, it may seem like common sense but it’s a good way to reduce misunderstandings due to inconsistency of terminology.
  • Define boundaries to consider edge cases from the beginning of a system implementation. This will help you reduce the risk of discovering bugs at a late stage of the development.

These concepts are an essential understanding of how to elicit requirements and write better specifications.

The “WHAT” and “HOW”, and why they’re different

As Gojko writes in “Bridging the Communication Gap”:

In order to get the most out of acceptance tests, we need to distill what should be done from the discussion and not really focus on how it is going to work.

Specification By Example

When people mix up the “WHAT” and the "HOW" they create specifications that are difficult to read for business people. It is common to get specifications that include lines of code. That must be avoided because acceptance tests are a deliverable that needs to be written by business people together with developers and testers to ensure a common understanding of what needs to be built so that we can meet client's expectations. "HOW" should also be kept separate from the "WHAT" as the Acceptance tests are Living Documentation: the examples are the only executable part of the test, and they should clearly show the relationship between the inputs and the outputs otherwise they can't be automated. If we include unnecessary details, the specification becomes impossible to maintain, change, and execute and will go out of date very quickly.


In just 2 days, I learned more than I could imagine from Gojko's course. In addition to the concepts outlined above, it was extremely useful to see how he facilitates an SBE Workshop. A good facilitator is essential to involve people in the discussion and end the session achieving the most important goal: build the right product and improve its quality, by encouraging the collaboration between the delivery team, business people and users. This ensures a shared understanding of the reason why we are building a product, which leads to writing better requirements from the start of the developing cycle.

P.S I'd like to thank my classmates, for their willingness to share experience and knowledge :-)

About the author

Giulia has worked as a design consultant and art director in an integrated communications agency for more than ten years, developing both the design talent and business knowledge necessary for creating meaningful holistic brand experiences.

Giulia joined Codurance driven by the desire to apply the Software Craftsmanship mindset and values to the whole product and service design process.

She is a Certified Scrum Master and Certified Scrum Product Owner with a strong focus on the present and the future of a product, backed up by her Integrated Design background and the mastery of User Experience Design skills.

Aiming to bridge stakeholders and development teams, she facilitates their collaboration in designing solutions that balance business needs, technical feasibility and user expectations, with tools like Impact Mapping and User Story Mapping.

She believes in continuous learning, and her current interest is Product Strategy and User Experience Design for Conversational Interfaces and Internet of Things technologies.