Nicholas Van Weerdenburg wrote:

> ...
> Iwan van der Kleyn wrote:
>> ...
>> 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'm pretty sure that any new source code documentation has been going 
into the 1.8.2 source; any way, that's what's being displayed at

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

(I would think, though, that applicable docs would also go into the 1.9 
tree.)

The 1.9 docs had been onlne, too, at one point, but have been taken 
down; I wasn't keeping up with the changes, and it seemed of far less 
general value then the other 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.

It is a credit to Ruby's design that one can get a grasp of the 
essential principles and syntax without having to keep track of too many 
exceptions.  So, for example, you can initially assume that everything 
is an object, or that every method returns the value of the last 
expression executed, and later on worry about the exceptions to these 
things.

But that is of limited value when you get down to specific libraries and 
you just have to know the API.

> 
> 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.

I'd really like to think this was true, but I just don't see it. 
Obsessed?  There may be some who rant about it more than others, but I 
think, overall, you hear far more about new libraries and frameworks 
than about documentation.  Activity on the ruby-doc list is quite low; I 
believe many original members have simply dropped out.  I think we're on 
the verge of becoming a secret cult.

> 
> 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/

These are 1.8.2 docs, and I believe the bulk of the additions and 
updates have been coming from the members of the Ruby Documentation 
Project, plus the library developers themselves.

"The documentation itself has been created by Gavin Sinclair, William 
Webber, Lyle Johnson, and library authors. Individual library files 
usually have code and documentation credits."

> 
> 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.

Well, I think what you are referring to as the 1.9 docs are in fact the 
1.8.2 docs


James  Britt
www.ruby-doc.org