---
layout: post
title: Cucumber / Rspec and documentation as one
tags:
- Development
- Personal improvement
status: publish
type: post
published: true
meta:
  _edit_last: '1'
---
A Ruby developer I met recently told me that the majority of us Rubyists skip documentation in favor of <a href="http://en.wikipedia.org/wiki/Test-driven_development">Test Driven Development</a> tools. Some business are still pretty <a title="Waterfall design process" href="http://en.wikipedia.org/wiki/Waterfall_model">waterfall oriented</a> and demand all the requirements gathering, business analysis and design beforehand, as well as hard documentation with lots of funny terms and fancy diagrams.

I told her I was looking forward to studying <a href="http://cukes.info">Cucumber</a> and <a href="http://rspec.info">Rspec</a> in order to improve my skills. She asked me how I did documentation using those tools and I answered: “Cucumber and Rspec are the documentation”. As she twisted her nose I could tell I had to research more on the topic; so I did.

<!--more-->

I have been reading the Rspec book. Definitely read it if you want to know how to code better.
<h3>Why does “documentation” feel so hard?</h3>
Dumb answer: <em>It sucks</em>. Smart answer would be something like: <em>You might be doing it wrong</em>.

Documentation specifies a software's collection of procedures it performs. Why should we even try and build software that does not resemble people's expectations? (If it weren't Ruby, I'd guess the software to be built required another form of understanding, which is fine and yet irrelevant in this case.)
<h3>Who is the documentation for?</h3>
Not just people, but stakeholders who want straightforward answers. 150 pages of paper is not the way to accomplish that, IMO. They know what they asked for and we should build the answers accordingly.
<h3>Cucumber and Rspec</h3>
What's wrong with automated documentation? How beautiful is it to have a stakeholder look to a set of Cucumber features and Rspec examples that assert precisely what he asked for — damn, he might have written those features…! — and find the answer?

Cucumber defines vocabulary for the system, states what it does and who. And it helps developers and stakeholders connect and collaborate.

PS: being a designer, I know I must present my documentation as pleasant as possible. Well, I guess Cucumber and Rspec just support this statement of mine, don't they…?