Not to be rude, but 1.8.7 is dead. RubySpec is first, not linked from [1] and second, just about completely inaccessible to someone not already familiar with Ruby. It's an executable specification, not a language reference manual. It's aims, structure, and information architecture are inappropriate for the purposes of a human with questions about the language, ala "what's the syntax and semantics for X in Ruby 2.0?" (for X = case, method definition, etc., etc.)
We're already starting to see third-party sources bitrotting. E.g. eigenclass' 1.9 pages are now gone. Without an authoritative source for "What's new in 1.9.x?" and later, this bitrot will get worse and make it needlessly painful for folks who still need to move 1.8 code (or brains...) to 1.9/2.0.
Part of my point is that the sources directly linked from ruby-lang.org are a mish-mash as well. There's virtually nothing authoritative, maintained by ruby-lang.org itself. The links at [1] are a mix of ok, good, and rather out of date. ruby-doc.org, not linked from [1] (wat.), is about as good as we've got for a standard reference. Sadly, it's missing the language reference piece and it's auto-generated information architecture sucks hard.
An example of that last point: hit [2]. What's above the fold? A useless list of files. Scroll down and you'll eventually get to the filterable lists of core classes and methods. Click on "Array"[3] and we actually get a nice summary doc with examples that walks us through this class.
For comparison, we'll go to the standard library[4]. Click on "net/http" in the left sidebar[5]. Instead of getting a nice summary page, instead we get an opaque class and method list. The reader is left to divine which, if any, link might provide some clues about the use and organization of this library. (Hint: it's "Net::HTTP", third from the top on the left.) If you already know which is the "main" class for this library, then you can usually guess right.
It's ridiculous for reference material to assume the user is already familiar with it in order to successfully navigate it. Again, other languages' library references do a much better job w.r.t. navigability.
Coda: I don't mean to harsh on ruby-doc.org too much; it's just a central example in the Ruby world. Nevertheless I feel the need to highlight how the Ruby community's disconnected, scattershot approach to documentation presents both a user education and a marketing problem.
We're already starting to see third-party sources bitrotting. E.g. eigenclass' 1.9 pages are now gone. Without an authoritative source for "What's new in 1.9.x?" and later, this bitrot will get worse and make it needlessly painful for folks who still need to move 1.8 code (or brains...) to 1.9/2.0.
Part of my point is that the sources directly linked from ruby-lang.org are a mish-mash as well. There's virtually nothing authoritative, maintained by ruby-lang.org itself. The links at [1] are a mix of ok, good, and rather out of date. ruby-doc.org, not linked from [1] (wat.), is about as good as we've got for a standard reference. Sadly, it's missing the language reference piece and it's auto-generated information architecture sucks hard.
An example of that last point: hit [2]. What's above the fold? A useless list of files. Scroll down and you'll eventually get to the filterable lists of core classes and methods. Click on "Array"[3] and we actually get a nice summary doc with examples that walks us through this class.
For comparison, we'll go to the standard library[4]. Click on "net/http" in the left sidebar[5]. Instead of getting a nice summary page, instead we get an opaque class and method list. The reader is left to divine which, if any, link might provide some clues about the use and organization of this library. (Hint: it's "Net::HTTP", third from the top on the left.) If you already know which is the "main" class for this library, then you can usually guess right.
It's ridiculous for reference material to assume the user is already familiar with it in order to successfully navigate it. Again, other languages' library references do a much better job w.r.t. navigability.
Coda: I don't mean to harsh on ruby-doc.org too much; it's just a central example in the Ruby world. Nevertheless I feel the need to highlight how the Ruby community's disconnected, scattershot approach to documentation presents both a user education and a marketing problem.
[1] https://www.ruby-lang.org/en/documentation/
[2] http://ruby-doc.org/core-2.0.0/
[3] http://ruby-doc.org/core-2.0.0/Array.html
[4] http://ruby-doc.org/stdlib-2.0.0/
[5] http://ruby-doc.org/stdlib-2.0.0/libdoc/net/http/rdoc/index....