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
