Leaving the click-bait title aside this will be an article about writing good specs

This year I learned something that I kinda guessed already: The biggest benefit of keeping a journal is not archiving your experiences. Very few people take the time to read what they wrote 5 years ago. The biggest benefit is in the writing process alone. Writing helps you clarify your thoughts and feelings. According to science: writing accesses your left brain, the analytical and rational, so your right side is free to create, brainstorm or mix ideas.

Journaling and writing specs have a lot in common. The benefits for me are strikingly similar. This quote sums it up perfectly:

“I write to understand as much as to be understood”

— Elie Wiesel

For me placing pixels on the screen helped me communicate better what I had in mind. I did this for years. Until 3-4 years ago when, in an effort to improve the quality of our releases, we decided to use integration tests. And for that we looked at Gherkin as a way to define these tests. I was familiar with Cucumber and I looked at it back in 2008 but ditched it an un-necessary complication. Then I slowly adopted it and now it's the go-to way of defining what a product should do.

What is Gherkin anyway?

It is a Business Readable, Domain Specific Language that lets you describe software’s behaviour without detailing how that behaviour is implemented. It's mainly used for automated tests and for features documentation. In other words it's a text file that looks something like this:

Feature: Some terse yet descriptive text of what is desired
  Textual description of the business value of this feature
  Business rules that govern the scope of the feature
  Any additional information that will make the feature easier to understand

  Scenario: Some determinable business situation
    Given some precondition
      And some other precondition
     When some action by the actor
      And some other action
      And yet another action
     Then some testable outcome is achieved
      And something else we can check happens too

  Scenario: A different situation
      ...

You can read all about it on the Cucumber Github page.

Back to the benefits

There are few hidden benefits of Gherkin that go beyond its benefits for Q&A:

Focus on behaviour

You can screw up the specs easily. The way I did that in the past was to focus a lot/only on visuals. I wrote things like:

As a user 
When I click on the button on the top left
Then I should see a drop-down with this and that

I was using this tool to describe the wireframe or the Photoshop file.
The real benefits for me came once I forced myself to describe behaviour, not layout and doing this before I thought about the interface. Once you describe the behaviour the layout comes naturally. Remember: design is not how it looks, but how it works.

Communicate through examples

I think most product people have the "gift" of compartmentalizing things. I am super good at this but this doesn't help that much when you are speccing something. Working with abstract data is the best method to ignore the details (and in the tech industry it's all about the details) and makes it hard to communicate the spec in the first place.

Now instead of writing "the report will display a title" (just to give an example) I try to come up with a few titles. Not only will this be easier to follow but if a designer is working on this spec then having a few titles to work with will tell him a few things about the assets he is working with. And if I am working with an existing feature then I would probably want to see some of the titles people use to offer some real-life examples.

Discover corner cases

A funny thing happened as I am writing all the use-cases. I started asking all sorts of questions. "What happens if this is that?", "How will this work in that context?" etc. It's hard to explain especially since in hindsight these corner cases don't need a special language to be spotted. Or so I thought. But in practice: looking at a blank screen and trying to describe how something will work is the only way that I can spot these problems.

Better communication inside the team

The larger the team gets more and more people will want to be in the loop with what is getting built. The marketing team will want to plan for a release and so will the sales team. The CEO may want to see what's going on ... All of these generally good things. Or you may want them involved for feedback.
The beauty of having documented use-cases using Gherkin is that anyone in the company can read those. If they don't speak English that's fine too as you can write those in any language you wish.

Helps with estimates

Not to mention that the more you detail the specs the more precise will the estimates from the engineers be. I truly believe that poor estimation is first of all a problem of poor specs. Not the only issues but one of the most important ones.

TL;DR:

Gherkin is a great tool for writing use-cases and creating some kick-ass specs. Use it!

These tips will make you a better product guy