blob: bc9897035e2dc09699151a28a499a2419e7add18 (
plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
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...?
|
