diff options
Diffstat (limited to '_posts/2011-08-02-cucumber-rspec-and-documentation-as-one.markdown')
| -rw-r--r-- | _posts/2011-08-02-cucumber-rspec-and-documentation-as-one.markdown | 58 |
1 files changed, 58 insertions, 0 deletions
diff --git a/_posts/2011-08-02-cucumber-rspec-and-documentation-as-one.markdown b/_posts/2011-08-02-cucumber-rspec-and-documentation-as-one.markdown new file mode 100644 index 0000000..bc98970 --- /dev/null +++ b/_posts/2011-08-02-cucumber-rspec-and-documentation-as-one.markdown @@ -0,0 +1,58 @@ +--- +layout: post +title: Cucumber / Rspec and documentation as one +tags: +- Development +- Personal improvement +type: post +published: true +--- + +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. + +I have been reading the Rspec book. Definitely read it if you want to know how +to code better. + +### Why does “documentation” feel so hard? + +Dumb answer: _It sucks_. Smart answer would be something like: _You +might be doing it wrong_. + +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.) + +### Who is the documentation for? + +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. + +### Cucumber and Rspec + +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...? |