[rspec-users] Reorganize documentation for Cucumber at Github

Andrew Premdas apremdas at gmail.com
Sun Jan 18 12:06:39 EST 2009


I'd just like to point out that the Github wiki tool is somewhat challenged
by a project with so much good documentation like cucumber has. The lack of
search, and the layout is really poor. Might it be better to host a more
able wiki on another site, and use the github wiki to point to this external
documentation?

All best

Andrew


2009/1/18 aslak hellesoy <aslak.hellesoy at gmail.com>

>
>
> On Sun, Jan 18, 2009 at 1:34 AM, aslak hellesoy <aslak.hellesoy at gmail.com>wrote:
>
>>
>>
>> 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?
>>
>
> 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.
> 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 as example. No
> Rake yet - just the cucumber command)
> 6) What does the output from Cucumber mean? (Learn to read the deafault
> console output. Colours and error messages. Mention other formatters)
> 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.
> 8) How to implement the body of a step definition. Learn about RSpec's
> #should and #should_not - and matchers
> 9) How to fix a failing (red) step definition by writing some code (in lib
> for now since we're not doing any Rails)
> 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.
> 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)
> 14) Learn about hooks (Before, After etc)
> 15) Various other features (CUCUMBER_COLORS, AutoTest, cucumber.yml
> (profiles)
> 16) IDE support
> 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)
>
> 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
>
>
>> 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 (::)
>>
>
>
>
> --
> Aslak (::)
>
> _______________________________________________
> rspec-users mailing list
> rspec-users at rubyforge.org
> http://rubyforge.org/mailman/listinfo/rspec-users
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://rubyforge.org/pipermail/rspec-users/attachments/20090118/fc8aae36/attachment-0001.html>


More information about the rspec-users mailing list