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

David Chelimsky dchelimsky at gmail.com
Sun Nov 8 07:32:50 EST 2009

On Sat, Nov 7, 2009 at 11:39 PM, Stephen Eley <sfeley at gmail.com> wrote:

> 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.

Executable documentation is what I'm after. If Cucumber is not giving that
to us now, then I'd like to use this opportunity to push in that direction.
The whole point is to bind the documentation to the code so that as the code
evolves, the documentation is less likely to stray from it.

> 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).

Have you looked at
for example? I don't think Given/When/Then are going to confuse anybody in
this case.

> 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?

That's what the narrative area is for, in part. And where that is
inappropriate, we should have a way to build a website that integrates
cucumber pages with plain HTML pages. Something like webby with a plugin for
running the .feature files and storing the output as HTML pages. The
examples of what the code looks like should be executable.

> 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.

Great. My goal is to have an integrated result, but that doesn't mean that
people can't contribute to prose separately from scenarios.

> Have Fun,

I usually do :)


>   Steve Eley (sfeley at gmail.com)
>   ESCAPE POD - The Science Fiction Podcast Magazine
>   http://www.escapepod.org
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://rubyforge.org/pipermail/rspec-users/attachments/20091108/a698738f/attachment-0001.html>

More information about the rspec-users mailing list