Book ReviewProgramming

Book Review: Writing Great Specifications

Today I’ll give you my insights about an interesting little book called Writing Great Specifications by Kamil Nicieja available from MEAP or Amazon.


The book is all about writing executable specifications. Some relevant keywords here are specification by example, behaviour-driven development or acceptance test-driven development.

The author starts it easy with an introduction to Gherkin – a structured language that allows us to write readable tests. There is a whole chapter on the corresponding given-when-then template which starts to bring up a few finer points.

The next chapters cover how to structure specification files. First internally, then it dives into things like folder layouts for a larger number of specification files. The author has tackled large projects with this approach which becomes apparent when he explains the various layout approaches and their pros and cons.

I particularly liked the chapter on refactoring specifications. Since these files are part of a test suite they should be similarly maintained and it’s just common sense that refactoring applies as well. However, the techniques clearly differ from normal source code, so it is an interesting read nevertheless.

Finally, Kamil brings it all around by moving towards domain-driven design (DDD) and how embracing it leads you to a different and more nuanced view of your executable specifications. In particular in light of the ubiquitous language at the heart of DDD, the power of these specifications really shows well. The author gladly did not just scratch the surface here, but dedicated two entire chapters to this convincing combination of DDD and Gherkin.

Target Audience

Clearly, everyone writing executable specifications benefits from this book. But if you’re even just interested in how you could pull this off, the author does a good job of explaining what it’s all about. It’s a solid introduction to Gherkin and opens your eyes to a different world if you’re used to having complex requirements and hard to understand tests.


The book takes an interesting approach by focusing solely on the specification part of Gherkin. There is an automation layer beneath it that is required to actually make these specifications executable. However, the author goes to great lengths in order to avoid discussing this layer any more than absolutely necessary. He even moved most of that explanation into an appendix.

At the beginning this decision may make you feel like you’re missing out on something important. But the further along you get in the book, the clearer it becomes that this is a fabulous decision. It allows the author to relentlessly focus on what the title promised – writing great specifications. After all, execution is just a tiny part of a great specification.


Ruthlessly leaving out the automation layer is what makes this book unique to me. Instead of showing off some framework like cucumber, the author is very disciplined in focusing on the title matter. As with everything in software development, once you learned about the topic you’ve just seen the tip of an iceberg. This book takes you along on a deep dive into the vast realm of great specifications.

It may not be useful to everyone and a good book about writing techniques may indeed be better for your needs. But if you are involved with or are thinking about Gherkin-style specifications, this book will be a treasure to you.