From: Nicholas Van Weerdenburg <nick@...>
Date: 2004-12-04T01:49:32+09:00
Subject: Re: Ruby documentation.


Iwan van der Kleyn wrote:

> Nicholas Van Weerdenburg wrote:
>
>> I think that may have been the case a few years ago, 
>
>
> Although that may be true, I think that the present state of Ruby's 
> 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.
>
> Don't get me wrong. I've been busy with Ruby for a few weeks now. I 
> like the language and think the implementation is superb. The pickaxe 
> book is indeed excellent. On par with Learning Python (with better 
> practical examples) and probably a bit better than Learning Perl.
>
> However, the reference documentation is of "irregular" quality at 
> best. The soap or socket modules are good examples. They are not 
> documented at all. For me these modules are not "less common"...
>
> This is not to troll by the way. If I decide to stick around with Ruby 
> I;ll probably do my bit to help. But I do think that it's an issue 
> which should be taken seriously.
>
Those are good points, and important ones. 

I think there is a serious commitment, and it's taken very seriously.  
I've been using Ruby for about six months now, lurking for ten, and 
haven't lamented the documentation. But that many be because I haven't 
used some of the libraries that suffer from a lack of documentation. I 
also collected most of the Ruby books out there, and collected a lot of 
sample code.

Also- look for the 1.9 online documentation- my understanding is that 
it's had a lot added due to the generosity of the Pickaxe authors and 
the team who updated the docs.

I do come from a C/C++/Java background, so it did take some time to 
adjust to the new paradigms. But that wasn't due to a lack of documentation.

There also is a lot of effort going on in the area- to the point that 
the Ruby community is obsessed with documentation. I think it's a bit 
self-concious due to the years without. I expect that this is a good 
thing, since it promises more rapid growth in documentation.

Also- look for the 1.9 online documentation- my understanding is that 
it's had a lot added due to the generosity of the Pickaxe authors and 
the team who updated the docs.

http://www.ruby-doc.org/stdlib/

Also, the sidebar plugin for FireFox is cool:
http://www.ruby-doc.org/docbar/

On that note, I'm still not exactly sure what the difference is between 
the latest 1.9 docs and 1.8.1. If someone could give a definitive 
clarification, that would be great.

Regards,
Nick