aslak hellesoy wrote:
On Sat, Jan 17, 2009 at 10:10 PM, Tom Cloyd <tomcl...@comcast.net
<mailto: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?
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 <mailto:t...@tomcloyd.com> >> (email)
<< TomCloyd.com >> (website) << sleightmind.wordpress.com
<http://sleightmind.wordpress.com> >> (mental health weblog)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
_______________________________________________
rspec-users mailing list
rspec-users@rubyforge.org <mailto:rspec-users@rubyforge.org>
http://rubyforge.org/mailman/listinfo/rspec-users
--
Aslak (::)
Aslak,
I can speak only for myself, but...
You're a genius. You nailed it, conceptually. You wrote exactly what
I've been thinking of. My own outline's going slowing, for the obvious
reason that I don't really know what I'm doing. So...
I especially like the part about your writing it, with feedback. There's
no one more qualified. And...it'll be right, from the beginning.
I'm really excited about this. I'm committed to getting myself launched
with Cucumber this weekend. Hey, you can help, if you want :).
Many, many thanks. (understatement)
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
