August 3rd, 2019 by Kevin Pimentel

If you thought you were going to be a developer and not have to deal with people, boy were you wrong. Programming is a team effort and communicating with other people is crucial. You have teammates, a project manager, a product manager, the cat manager, and the client.

With all of these people involved, how can we use specifications to improve the development process?

Clear #Goals

For starters, a good specification needs to be testable, it shouldn’t describe tests or how software works. Specifications need to contain the business functions, be clear and precise. Specifications are about getting to know the business.

If you were to read the specifications tomorrow or a year from tomorrow, the takeaway should be the same. Having examples in the specification is crucial for understanding what are essentially acceptance tests.

When defining a project it’s easy to get caught up in how something is going to work or how it should be done, but that’s a waste of time. I am a developer, and you might be too, we decide how software gets implemented. What we need is to understand the business functions.


Most people are visual creatures and don’t respond well to a great wall of text. If you show me a wall of text, I will look away, and yell: “get it away!”

Nobody has time to read all of that, not in the age of memes and info-graphics. I need bullet points, a table, maybe a meme, or maybe a small flow chart. But not a book.

Here’s an example of SKY member shipping:


  • Sky members receive a free catalog on all fruit purchases. Catalogs are not available to non sky members.
  • Cookie dough purchases do not receive a catalog.


This template is very precise and absolutely testable. The original example that this template is based on can be found in Specification By Example Chapter 8.

I can take this example and write my acceptance tests. This example doesn’t tell you how to write your tests or how the front-end should flow. It gives you the business, the business functions. (ayee)


By using examples in your specifications you can define business rules that are precise and clear. The specifications will be useful for documentation, but most importantly, they will communicate the business functions to the developers.

Kevin Pimentel

There are two types of people in the world: those that code, and those that don’t. I said that! Quote me. My name is Kevin and I’m one of the ones that codes.