Writing Great Specifications: Chapter 1

Introduction to specification by example and Gherkin by Kamil Nicieja

❗️ I did not write this book. These are my notes on each chapter.❗️

Developers have a hard time knowing if they are building the write thing. Business owners don’t always know how to tell developers what to make. Too often developers end up making the wrong thing or business owners don’t know how to describe what it is that they want from developers. The issue isn’t technology but communication between teams. That is where Specifications by Example comes in.

The point of this book is to help teams across the board talk to each other in a common language. There are things that developers know that business owners don’t and vice versa. Gherkin is a coding language designed to be the most human friendly but objective oriented language to help bridge this gap. It isn’t just write tests in a human friendly way — in requires an objective. It demands a beginning, middle and end result from your software. It accomplishes this using a Given, When, Then syntax, but how to properly use it will be the topic of the next chapter.

This chapter is what you need to understand before you start writing tests. 😊

When creating software, it has to matter to someone. In order to find that out you must be empathetic to other people’s problems. The most important objective is to 1. Make sure developers deliver the right software and 2. Deliver it the right way.

The obvious problem is that developers don’t have the time to find that out. It’s not their job to find out what clients want. That is the business owners job, but business owners don’t know what is possible with technology. So introduce the on-going development conundrum. How do you get both worlds to 1. Talk to each other and 2. Understand each other?

As defined by the book, it plans to introduce you to the SBE system, which stands for Specification By Example. This system is “a collaborative software development approach that facilitates collaboration by illustrating software requirements with concrete examples and automated acceptance tests.

All right. Sounds easy. But what does that mean exactly, and what does that look like? Some of that will be explained throughout the following chapters, but the introduction does cement some core vocabulary before moving on.

What is specification?

Specification — is an analysis of a system and its design, made to plan and execute the implementation.

In order to make a specification you need to have a list of requirements.

What is a requirement?

Requirement — is a capability or condition that must be met or possessed by a solution to satisfy market needs or a contract, a standard, a specification or other formality imposed documents.

The problem that most teams run into is that they start looking at these specification documents like a recipe for cooking. These are not that.

While projects remain small, the chances that specification documents become an issue remains really small, but as soon as the project gets bigger the specification documents quickly run away from the developers. It must be seen as a living document that can be updated as you go along, with EVERYONE who is involved. You can’t treat it like your grandmother’s recipe that can not be altered. You must infuse flexibility.

“The main and only reason teams need specifications is information asymmetry. Teams need to distribute information evenly among the stakeholders to create the best possible product. If they don’t, they’ll miss critical requirements and make an incomplete product — or even a broken one.”

Information asymmetry — a situation in which one party has more information than another.

Specifications help address this information asymmetry through defining what and/or how it needs to be done.

One of the ways that you start setting abstract concepts into concrete measurements of what is wanted/needed is by inserting acceptance criteria.

Acceptance criteria — A condition or quality measure that a software product must meet to satisfy requirements.

“Acceptance criteria illustrates requirements. You should be able to use a criterion to evaluate the system and get an unambiguous confirmation that the system either passes or fails your test.”