[rspec-users] Reorganize documentation for Cucumber at Github

Tom Cloyd tomcloyd at comcast.net
Sat Jan 17 19:50:30 EST 2009

aslak hellesoy 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?
> Aslak
>     I'm working on this thing right now, and maybe it'll be far enough
>     along for some kind of review this weekend. Or...I could put it
>     up, say on a Google Sites wiki, and several of us could work on
>     it. Any thoughts? I actually prefer to work in a group, but have
>     already started on my own.
>     Yeah, I like that idea - a temporary Google Sites wiki.
>     Tom
>     -- 
>     ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
>     Tom Cloyd, MS MA, LMHC - Private practice Psychotherapist
>     Bellingham, Washington, U.S.A: (360) 920-1226
>     << tc at tomcloyd.com <mailto:tc at tomcloyd.com> >> (email)
>     << TomCloyd.com >> (website) << sleightmind.wordpress.com
>     <http://sleightmind.wordpress.com> >> (mental health weblog)
>     ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
>     _______________________________________________
>     rspec-users mailing list
>     rspec-users at rubyforge.org <mailto:rspec-users at rubyforge.org>
>     http://rubyforge.org/mailman/listinfo/rspec-users
> -- 
> Aslak (::)

I can speak only for myself, but...

You're a genius. You nailed it, conceptually. You wrote exactly what
I've been thinking of. My own outline's going slowing, for the obvious
reason that I don't really know what I'm doing. So...

I especially like the part about your writing it, with feedback. There's
no one more qualified. And...it'll be right, from the beginning.

I'm really excited about this. I'm committed to getting myself launched
with Cucumber this weekend. Hey, you can help, if you want  :).

Many, many thanks. (understatement)



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