[rspec-users] Reorganize documentation for Cucumber at Github

Tom Cloyd tomcloyd at comcast.net
Sat Jan 17 21:40:14 EST 2009

aslak hellesoy wrote:
> On Sun, Jan 18, 2009 at 1:34 AM, aslak hellesoy 
> <aslak.hellesoy at gmail.com <mailto:aslak.hellesoy at gmail.com>> wrote:
>     On Sat, Jan 17, 2009 at 10:10 PM, Tom Cloyd <tomcloyd at comcast.net
>     <mailto:tomcloyd at comcast.net>> wrote:
>         Fernando Perez wrote:
>             Hi,
>             I actually just noticed that Cucumber has plenty good
>             documentation on
>             its wiki at github. But the problems are:
>             - The homepage is badly designed as it doesn't really
>             outline an order
>             to read other pages
>             - It is impossible to make the difference between internal
>             links to the
>             wiki and links that will bring us some where else unless
>             we hover over
>             the link
>             - Pages don't link to each other such as: read next page
>             or previous
>             page, or related pages
>             - Pages are just sorted alphabetically which is not a
>             proper way of
>             sorting
>             Would it be possible to at least number the pages in the
>             order in which
>             we should read as if we were reading a book about cucumber?
>             The documentation seems excellent but is definitely not
>             well marketed
>             for new comers :)
>         Oh, I totally agree. Add in the fact that the Rails stuff is
>         just a mess for non-Rails people to read, and we really have
>         two problems to solve. That's how I, at least, have been
>         experiencing it.
>         My own solution is to build my own procedural outline. I'm
>         working on it today, in fact - sort of a "Cucumber for
>         dummies" document. In my conception, liberal use will be made
>         of links to existing pages, or to sections thereof, as there's
>         no need to attempt to redo what the experts have already done
>         well. I figure if I write what I wish I'd encountered when I
>         went to the wiki, and then see if I can get it there, it might
>         help other folks.
>         Your final sentence says it all - great documentation, but not
>         for newbies. Where's the starting point? Etc.
>     Where is the starting point! There is none! Haha. And the GitHub
>     Wiki Home page is probably the worst page in the whole Wiki.
>     Honestly - I think what's needed is:
>     1) Move a lot of the random stuff from Home to separate pages
>     2) Make the Home page really short - with links to a few new pages:
>     * General Five Minute Introduction (Pure Cucumber/Ruby stuff - no
>     Rails) - Narrative, sequential style, link to other specific pages
>     - ideally most of them.
>     * Rails-specific Five Minute Introduction (to be read after the
>     other 5 minute one). Cucumber Backgrounder is a very good start
>     for this, but I think it's a little rambling :-)
>     I'd like to write these intros myself, so please don't start doing
>     massive edits. Instead, I'd love to get input of an outline for
>     these Introduction pages.
>     How does that sound?
> Ok, I'll give a stab at what a 5 minute introduction might contain. 
> Please comment.
> 1) Who should use Cucumber, and what benefits can you get from it?
> 2) How Cucumber works (high level explanation without getting too 
> technical).
> 3) Learn the nomenclature - features, scenarios, steps (step 
> definitions later). Some style guidlines.
Totally agree. This is the "shoehorn" I was looking for - partly. Having 
YOU write it would be far far better than anyone else, because of your 
knowledge and communication skills. People like me can best serve by 
giving feedback, as the writing proceeds.
> 4) What does a Cucumber feature look like (plain - no outlines or 
> tables). Learn how to write one in a simple text editor.
> 5) How to install and run Cucumber (using the one from 3
you mean "4"?
> as example. No Rake yet - just the cucumber command)
Yeah. Keep it minimal, but something that will actually run and produce 
results to study. Which leads us to...
> 6) What does the output from Cucumber mean? (Learn to read the 
> deafault console output. Colours and error messages. Mention other 
> formatters)
yes yes yes
> 7) Learn to write step definitions (they are similar to defining 
> methods in most imperative languages like Ruby, Java, C, Pascal....). 
> Mention Regexps, Rubular.com.
Would be very very helpful.
> 8) How to implement the body of a step definition. Learn about RSpec's 
> #should and #should_not - and matchers
Man, could I use this. Things go really dark for me at this point. Just 
haven't gotten there yet.
> 9) How to fix a failing (red) step definition by writing some code (in 
> lib for now since we're not doing any Rails)
Yes. Especially the part about excluding Rails. And this, to me looks 
like the end of the beginning. What follows is very helpful, but by this 
point the boat is launched. I DO dearly want the rest of what you've 
written, however, so don't drop anything from the outline, if you have 
the time to carry through to the end.
> 10) Mention DTSTTCPW and refactoring - with some external links. TDD 
> basics.
> 11) Learn how to use Rake (useful when you have more than one feature 
> file). Mention RCov.
Nos. 10-11 look especially interesting to me.
> 12) Learn about the various command-line switches
> 13) Learn about more advanced Gherkin (Cucumber language) features 
> such as Tables, PyString, Scenario Outlines and Background (coming soon)
I'm not sure, but I'm thinking that Tables and Scenario Outlines (to the 
extent that I understand them) might well come earlier in the outline. 
On the other hand, those of us who want to could simple skip ahead to 
grab the material when we need it.
> 14) Learn about hooks (Before, After etc)
> 15) Various other features (CUCUMBER_COLORS, AutoTest, cucumber.yml 
> (profiles)
 From here on, I think we're into the "and it'd be nice if we had 
something about..." territory. Dessert.
> 16) IDE support
Interesting. I work exclusively with the CLI, and love it. Used to work 
with IDEs, but converted.
> 17) How to use other assertion tools like Test::Unit, Shoulda, etc.
> 18) How to use Cukes with non-Ruby platforms (Watir family, JRuby, 
> IronRuby, FunFX/Flex)
Terrific outline, I'd say. I cannot imagine not getting what I want, 
from this material. It'll suck people like me into the process, and when 
we get into trouble we can shout out, which will lead to possible 
additions (but I don't think they'll be major).

I'll stay glued to me email inbox (and the wiki) to watch this develop. 
This is a gift I simply didn't expect, and especially not right when I 
most need it.

This is going to be very very helpful, and to an increasing number of 
people, I'll predict.

I'm excited about this development. Thanks so much.

> The reader will gradually learn about the recommended file layout 
> structure.
> Maybe this is more like a 10-15 minute intro. I'll try to keep it as 
> short as possible without skipping important concepts.
> What's missing? What's in the wrong order? What should I remove?
> Aslak


Tom Cloyd, MS MA, LMHC - Private practice Psychotherapist
Bellingham, Washington, U.S.A: (360) 920-1226
<< tc at tomcloyd.com >> (email)
<< TomCloyd.com >> (website) 
<< sleightmind.wordpress.com >> (mental health weblog)

More information about the rspec-users mailing list