From: Chris White <cwprogram@...>
Date: 2011-09-12T02:24:12+09:00
Subject: Re: De-listing of ruby-doc.org on ruby-lang.org?


> While we're at it, I'll mention something annoying me to no end for
> some time now: ruby-doc.org's stdlib documentation is missing for some
> libs. Go to http://ruby-doc.org/stdlib/ and start clicking links on
> the left - soon enough you'll find some what return a 404. For
> example, Win32API, soap, readbytes, and I haven't even checked a third
> of the list.
>
> If the docs for these are actually missing, then you should show some
> user-friendly messages or at least a list of methods, like
> rubydoc.info does.

Towards the end of last month I uploaded some updated documentation to a free Heroku instance:

http://furious-waterfall-55.heroku.com/

Note: this is a free Heroku instance so it will be pretty flakey. However all the files served are static so it won't be too bad hopefully.

When contacting the ruby-doc.org maintainer about having it hosted for the time being, he stated that there were going to be updates at some point. He also stated that there are issues with the way that RDoc does some of the processing of class hierarchy, so a custom tool is used. I've requested more information but haven't heard anything back yet. At any rate, the URL above uses an updated rdoc with the darkfish template. On a side note I'm trying to put together a Ruby Language Guide. In essence I'd like to make it something more organized. The problem with the current state of documentation from a reference perspective is that it lacks an organized structure. Take for example the Array class. Arrays have methods for obtaining values, modifying values, and iterating over values. This sort of categorization is simply too difficult to automate given the current state of things, and would require linking to some kind of external metadata. 

Also the inline documentation samples are very concise (part of which is to not create walls of comments in the code) and are often written in a "here's the input and here's the output" style. There are some cases to where showing usage more tailed towards real world use requires much more detailed code.

Regards,
Chris White
Twitter: http://www.twitter.com/cwgem