David Heinemeier Hansson wrote:
Despite the snazzy look of the new default RDoc templates with three panes at the top, I keep coming back to the original flat look of http://www.rubycentral.com/book/builtins.html\. There's something deeply usable with having all the modules and methods take up a full screen instead of being cramped into tiny panes at the top. Of course, it could also be, as Dave Thomas suggested, that I'm just "getting old and inflexible".
I don't have the time to do it either, but I'd really appreciate it too. If (like me) you constantly use Firefox/Mozilla's type-ahead-find feature you'll be messed up constantly by framed sites.
There are lots of problems with the online ruby book HTML, but I've always found it much more useable than any of the rdoc documentation.
I think the absolute ideal of Ruby documentation would be something along the lines of:
* Ruby language reference
* keywords and their meanings
* alias
alias <new name> <old name>
example:
alias oldBackquote `
def `(cmd)
result = oldBackquote(cmd)
if $? != 0
raise "Command #{cmd} failed"
end
result
end
print `date`
print `data`
...
* rescue
rescue <ExceptionClassList>
rescue <ExceptionClassList> => <varname>
example:
begin
eval string
rescue SyntaxError, NameError => boom
print "String doesn't compile: " + boom
rescue StandardError => bang
print "Error running script: " + bang
end
...
* regexp reference
...
* m - multiline
...
* commandline reference
...
* Ruby core builtins
* Array
*
...
* each
...
* String
...
* length
...
* All ruby builtins
...
* CGI
...
* Process
...
* Test
* Unit
...
* Zlib
* GzipFile
* Ruby standard library
* soap
* webrick
* <webrick documentation or link to webrick documentation site>
* yaml
* <yaml documentation or link to yaml documentation site>
* Yaml
* dump
* load
As far as I know, the keyword documentation I'm dreaming of doesn't exist anywhere, but it would be just amazing to have. I always forget little details, like does 'alias' have symbols after it, or bare function names? Does it use a comma separator or whitespace? How do you assign a variable for the exception when you rescue it? What are the options for creating a multiline, case-insensitive regular expression?
As for the documentation of the built in classes, I think the builtins page linked above is a masterful work of UI design. It is exactly what's required when you are asking yourself the question "What's the name of that method that converts an id number to a string, and what class is it in?"
I go to that page, and after a bit of quick scanning I spot Fixnum#id2name, I click on that and get an explanation and a great example.
The way that page is laid out, there are about 1.5 screens (for me) worth of text, all of it laid out in a clear hierarchy, all of it hyperlinked. Compare that to RDoc Documentation
The page is mostly blank, but at the top I get 3 scrollable frames, each about 20 "windows" long. It just isn't as easy to browse.
Once I choose a class/file the documentation is excellent and readable, but because of the frames, my type-ahead-find doesn't work.
Now, Ruby has gotten bigger between the release of the first book and the documentation on ruby-doc.org, but the list at the book site is still better for me. I use Array far more than I do Zlib::GzipFile::NoFooter. While they may both technically be part of the core, Array, String, Hash, etc. really deserve special status as inner core, or uber-mega core, or something. 99% of the time I find I'm looking up uber-mega core information or keywords, and Zlib::GzipFile::NoFooter just gets in the way.
My not-so-humble opinion. 
Ben
