From: James Britt <jamesUNDERBARb@...>
Date: 2004-12-04T02:33:16+09:00
Subject: Re: Ruby documentation.

Cameron McBride wrote:
> Just hitting the obvious points that have been discussed before: 
> 
> 
>>documentation is far from ideal. Newbies (like me) do not compare the
>>present state of affairs with how it used to be but compare it with the
>>availability and quality of documentation with Perl or Python. And both
>>languages are far superior in this respect.
> 
> 
> It is good to realize ruby docs are not on the same level as perl or
> python, but that
> shouldn't surprise anyone.  Those other communities are larger, and
> have been more active (at least in English based usage and discussion)
> for more years.  They also carry the other respective boons and banes
> of a larger community.
> 
> On the other hand, it's also good to realize the comparison is
> partially flawed.  In a Karate class, you don't say a 14 yr old has
> better technique than an 8 yr old just cause the former can kick the
> stuffing out of the latter.


This sort of hand waving does more harm than good.  Rationalizing the 
state of a language by citing its lack of maturity just feeds the idea 
that Ruby is not yet ready for prime time.

The comparison to Perl and Python is not flawed if people want to hold 
up Ruby as equal or better.  The available documentation either is or is 
not acceptable; different people have different needs and criteria, but 
no one is served by making excuses.


> 
> To address Iwan directly, not all documentation is 'ideal'  but I
> would definately classify most as usable.  And the fact that this has
> changed dramatically in the past couple of years means the ball is
> rolling and it is going to get better.  (sidenote: sincere thanks to
> those that have made this reality.  I might just be a lurker and minor
> user, but man - it is *so* appreciated)

As are words of thanks to those who have been building up the available 
bundled and online documentation resources.    Thank you.

> 
> Adam, like others have mentioned - the basics are pretty well
> explained.  You might hit a snag with a library or module here or
> there, but the general concensus is that if you post a "wtf is ...?"
> to the mailing list, you'll get a decent reply rather than an RTFM. 
> So it's really a question of what you want.
> 
> FWIW, I thought ruby was worth learning back in 2001 when the docs
> weren't to the current level and I don't read /speak a lick of
> Japanese.
> 
> Oh, and Iwan: documentation is taken VERY seriously here, no worries. ;)

Well, up to a point.  I would at least take out the word 'very'; there 
is still an overwhelming emphasis on code.  Some have outstanding 
documentation, while others have barely a README.

But maybe that's just the best use of resources.


James