[rspec-users] Reorganize documentation for Cucumber at Github

Tim Walker walketim at gmail.com
Sun Jan 18 12:57:27 EST 2009

This is great news. One possible way to do this incrementally on the
github wiki would be to create a subwiki (page?) called "the cucumber
book" (TCB) which has an organization and a little governnace around
change that is further defined just like what Aslak has so generously
created. From there the sections in TCB can grow in a controlled way,
the other stuff is just there as supporting information and special
subjects, etc. Just a thought. T

On Sun, Jan 18, 2009 at 10:06 AM, Andrew Premdas <apremdas at gmail.com> wrote:
> 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
> _______________________________________________
> rspec-users mailing list
> rspec-users at rubyforge.org
> http://rubyforge.org/mailman/listinfo/rspec-users

More information about the rspec-users mailing list