[rspec-users] [rspec-devel] describe "RSpec's documentation" do

Stephen Eley sfeley at gmail.com
Sat Nov 7 23:39:34 EST 2009

On Sat, Nov 7, 2009 at 9:31 PM, David Chelimsky <dchelimsky at gmail.com> wrote:
> As for internals, my goal for the Cucumber features is to provide an
> executable set of documentation for end users to understand how to use
> RSpec. Not so much to expose internals, which I think is better addressed in
> the RSpec code examples themselves. Make sense?

I'm sorry David; it might be because I haven't seen examples, but
conceptually I don't think this quite gels.  Some issues I have with
the idea:

1.) It's trying to achieve too many goals at once.  Application
verification and documentation are not the same problem.  If you try
to do both with the exact same files, I believe both will suffer.

2.) It creates an unnecessary knowledge dependency.  People who are
brand new to RSpec cannot be expected to have proficiency with
Cucumber just to read the docs.  I understand that they don't *have*
to execute the features, but if you don't know Cucumber at all, trying
to wrap your head around the feature syntax will distract from the
part that's important (understanding RSpec).

3.) The knowledge transfer would be inefficient, unclear, and
incomplete.  Too many concepts cannot be effectively communicated in a
"Given/When/Then" structure.  How do you explain the history and
philosophy of BDD in that syntax?  How do you explain the role of
"red, green, refactor" patterns within iterative RSpec development?
--Presuming you've figured out how to phrase that knowledge in a
Cucumber feature, how do you *execute* it?  And at that point what
have you gained?

Cucumber is great for many things.  I don't believe it would be a
great documentation tool at a "primer" level.  If anyone can show that
it can not only be done, but be done *well* in a way that will make
inherent sense to newbies and speed up their learning of RSpec, I'd
stand corrected and support this wholeheartedly.   Otherwise, I'd
suggest separating concerns, and not try to integrate and educate at
the same time.

---Having said that, I'm interested in contributing to the (prose, not
Cucumber) documentation effort.

Have Fun,
   Steve Eley (sfeley at gmail.com)
   ESCAPE POD - The Science Fiction Podcast Magazine

More information about the rspec-users mailing list