[rspec-users] Reorganize documentation for Cucumber at Github

aslak hellesoy 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:
>
>> 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 >> (email)
> << TomCloyd.com >> (website) << sleightmind.wordpress.com >> (mental
> health weblog)
> ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
>
>
> _______________________________________________
> rspec-users mailing list
> rspec-users at rubyforge.org
> http://rubyforge.org/mailman/listinfo/rspec-users
>



-- 
Aslak (::)
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://rubyforge.org/pipermail/rspec-users/attachments/20090118/0085f9d1/attachment-0001.html>


More information about the rspec-users mailing list