[rspec-users] Reorganize documentation for Cucumber at Github
aslak.hellesoy at gmail.com
Sat Jan 17 19:34:11 EST 2009
On Sat, Jan 17, 2009 at 10:10 PM, Tom Cloyd <tomcloyd at comcast.net> wrote:
> Fernando Perez wrote:
>> 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
>> 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
> 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
* 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
How does that sound?
> 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 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)
> rspec-users mailing list
> rspec-users at rubyforge.org
-------------- next part --------------
An HTML attachment was scrubbed...
More information about the rspec-users