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 <aprem...@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.helle...@gmail.com> >> >> >> On Sun, Jan 18, 2009 at 1:34 AM, aslak hellesoy <aslak.helle...@gmail.com> >> wrote: >>> >>> >>> On Sat, Jan 17, 2009 at 10:10 PM, Tom Cloyd <tomcl...@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 >>>> << t...@tomcloyd.com >> (email) >>>> << TomCloyd.com >> (website) << sleightmind.wordpress.com >> (mental >>>> health weblog) >>>> ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ >>>> >>>> _______________________________________________ >>>> rspec-users mailing list >>>> rspec-users@rubyforge.org >>>> http://rubyforge.org/mailman/listinfo/rspec-users >>> >>> >>> >>> -- >>> Aslak (::) >> >> >> >> -- >> Aslak (::) >> >> _______________________________________________ >> rspec-users mailing list >> rspec-users@rubyforge.org >> http://rubyforge.org/mailman/listinfo/rspec-users > > > _______________________________________________ > rspec-users mailing list > rspec-users@rubyforge.org > http://rubyforge.org/mailman/listinfo/rspec-users > _______________________________________________ rspec-users mailing list rspec-users@rubyforge.org http://rubyforge.org/mailman/listinfo/rspec-users
