Living Documentation in the BDD with Relish

BDD and Living Documentation

Bridging the communication Gap between Business and Technology is a main goal of the Behaviour Driven Development [BDD]. By adopting practices of BDD , we can write scenarios in human readable language so that non-technical people can understand scenarios and specifications. It’s always good idea to have scenarios in human readable language but there is a issue, where to write down those scenarios?. Here are few possible solutions that  you may think of 

  • Write down scenarios on Paper so that business people can read.
  • Write scenarios in the Collaborative Tools like Mingle, JIRA and tell business people to have a look.
  • You are free to keep it in the Source Control like SVN or Git.
  •  Use traditional approach like Excel sheets, Spreadsheets and keep it in the Google Docs or DropBox.

I am sure that, none of above is going to work well. “Business people like to use mouse than keyboard“. They like a nice, user friendly interface. Living Documentation is the solution to all these problems.

Living Documentation is a dynamic document which can be edited, updated and accessed collaboratively within the team. BDD enforces that your Feature files should serve as documentation. Anyone should understand system’s behaviour by reading your feature file.

Introduction to Relish

Relish is a awesome tool developed by Matt Wynne [@mattwynne] in order to host your feature files online. Relish is a easy to use tools and you can share feature files just by sharing links to your Relish project. Here are some cool feature features of the relish

  • Easy to use and install
  • Work with many BDD tools which supports Gherkin [ Behat, Cucumber, SpecFlow, etc etc ]
  • You can create multiple projects
  • Option to keep your projects private
  • Check for Gherkin Syntax error while pushing online.
  • Browser other public projects online & custom documentation with file.

There are more features to come. You can follow @relishapp on Twitter for more news and updates.

Get Started with Relish

In order to get started with Relish, you need to signup for the Relish by providing your email address. Once you signed up, you need to create Publisher in order to create your first project. You will guided well on the website. Here  is how ,I have created publisher for myself.


CreatePublisher in Relish


Install  Relish

Once you done with creating publisher. Its very easy to install Relish. You need to have RubyGems installed. You can simple run

I got something like this :


Add Relish Project

Once you installed Relish then you can your projects to relish. I have a ‘BehatDemo‘ project hosted on GitHub. So I will add same project to Relish. You need to provide Relish Credentials at this point i.e email address and pasword.

I have  project added to relish.


Push Your Features Online

Now that, we have created out Project on Relish. We need to push our feature files to that project. Navigate to your project path and push features online. Relish will look for ‘features’ directory and send all features online

You will get something like this:



Once you have pushed your features online, you can just share link to look at features file with easy and nice looking interface. The feature file we just pushed is averrable at Relish App project  Shashikant86/BehatDemo


Relish makes living documentation easy within the BDD project. You can host your projects and BDD feature files online and share with business people to read and contribute.