[rspec-users] Reorganize documentation for Cucumber at Github

aslak hellesoy aslak.hellesoy at gmail.com
Sat Jan 17 20:24:08 EST 2009

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

1) Who should use Cucumber, and what benefits can you get from it?
2) How Cucumber works (high level explanation without getting too
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,
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
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,

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
>> 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 (::)
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://rubyforge.org/pipermail/rspec-users/attachments/20090118/9bce00de/attachment-0001.html>

More information about the rspec-users mailing list