From 606a507fff5fc179764b8a0f5d26bc33334ebd86 Mon Sep 17 00:00:00 2001 From: José Mota Date: Mon, 22 Oct 2012 12:20:29 +0100 Subject: Remove UFZvalidator post and convert other two to markdown. --- ...ucumber-rspec-and-documentation-as-one.markdown | 58 ++++++++++++++++++++++ 1 file changed, 58 insertions(+) create mode 100644 _posts/2011-08-02-cucumber-rspec-and-documentation-as-one.markdown (limited to '_posts/2011-08-02-cucumber-rspec-and-documentation-as-one.markdown') 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 Test Driven + Development tools. Some business are still pretty waterfall + oriented 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 Cucumber and Rspec 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...? -- cgit v1.2.3-54-g00ecf