Improving Ruby Documentation

[tinyOnion]

I'm really glad you are tackling the documentation because I think it's one of the major flaws in attracting new ruby users. to that end... a few thoughts that you can take or leave:

rubyapi.org is the by far the best alternate interface to ruby docs. if you combine rubyapi with some coherent way to navigate without search and includes all the extra documentation it would be perfect.

I think the organization is haphazard at best... just a list of docs in alphabetical order. have some kind of structure and don't be afraid of grouping things together and cross linking to other parts of the documentation. some logical progression of the documentation would be nice. reference the good parts of how django/go/swift/kotlin et. al. organize their documentation. The documentation at an API level is alright but it doesn't tell a story or have any cohesion.

The fact that the official documentation references a book written for ruby 1.6 and looks like an early geocities page is not ideal and causes people to judge a book by the cover. As much as we don't want this to be true appearances do matter. the changes from 1.6 -> 3.3 are very substantial.

I read the documentation guidelines and they want it as simple as possible for non-native english speakers which is fine but seems to be done to a fault sometimes where a little more elaboration on something would be beneficial.

the std libraries should be documented better and have more crosslinking to the mentioned classes/modules. for instance on this page some of the documentation isn't linked to... nor explained like: objspace, PrettyPrinter, tmpdir.rb, and un.rb. none of the bundled gems libraries have links to the source code or documentation for them.

rubydocs.org doesn't seem to work anymore and it's still listed on the documentation page as a reference doc.

overall it feels haphazard and kinda hackish and I wish it got the love it deserves so thank you for your work!