Over a million developers have joined DZone.

Learning Specification by Example From Gojko Adzic

DZone 's Guide to

Learning Specification by Example From Gojko Adzic

What one Agile practitioner learned from, and how she got the most out of, a two-day course with an industry thought leader.

· Agile Zone ·
Free Resource

I recently had the pleasure to attend Gojko Adzic’s “Specification by Example: From User Stories to Acceptance Test" training course, taught by Gojko himself! Having read his brilliant books: “Bridging the Communication Gap,” and “Specification by Example: How successful teams deliver the right Software.”, I was very excited to get the chance to discuss my experiences of applying spec-by-example with the man himself. My goals for the course were as follows:

  • Put the theory I'd learned into practice with the hands-on exercises.

  • Learn something that I couldn't find in Gojko's books.

  • Refine my approach to Specification By Example.

I'm glad to say that the course did not disappoint! Here's what I learned. 

2-Days of 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 out of Specification By Example (SBE) and when to use it.

To get those essential concepts across to us, Gojko created two collaborative exercises, which aimed to simulate what happens when there is a lack of domain knowledge and the team is under time constraints. These are two typical situations in larger organizations.

Learning Something New

Thanks to the collaborative exercises, we went beyond the theory explained in the books, and we learnt how to write good specifications by experiencing how to run and facilitate a Specification By Example Workshop. We learned how to discover the right questions to ask by collaboratively visualizing a team's and the 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. This sounds obvious, but this can help to avoid an incorrect transfer of domain knowledge.

  • Identify modeling 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 an 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 essential to understanding 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.

Image title

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 alongside developers and testers, in order to ensure a common understanding of what needs to be built. The "HOW" should also be kept separate from the "WHAT," as the Acceptance tests are Living Documents. 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 automate. 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 have imagined 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 in involving people in the discussion and, by the end the session, achieving the most important goal: building the right product and improving its quality, by encouraging the collaboration between the delivery team, business people, and users. This ensures a shared understanding of why we are building a product, which leads to writing better requirements from the start of the development cycle.

P.S. I'd like to thank my classmates, for their willingness to share their experiences and knowledge!

specifications ,acceptance tests ,test automation

Published at DZone with permission of

Opinions expressed by DZone contributors are their own.

{{ parent.title || parent.header.title}}

{{ parent.tldr }}

{{ parent.urlSource.name }}