Rob Sanheim wrote:
> 2008/4/7 Song Ma <songmash / gmail.com>:
>> F.Y.I
>>
>>  Not sure if you guys have read this article, I am going to re-post it here.
>>
>>  http://glyphobet.net/blog/essay/228
> 
> The only good point in that whole mess is that the current state of
> docs for Ruby is poor, and could use a lot of love.

Well ... I guess that depends on which docs you are talking about. 
There's plenty of documentation on Rails, three of the major GUIs -- 
Shoes, FXRuby and QtRuby -- have books in "print" on them, there are two 
major Ruby "cookbooks", the documentation on Ruport and RSpec is 
excellent, etc.

A week or so ago when the Ruby Mendicant was considering working on the 
docs, I expressed the opinion that the documentation is the 
responsibility of the creator -- someone shouldn't have to do it for 
them. Now if the creator is a better coder than tech writer, perhaps the 
project can take on someone. But my experience has been that it's very 
rare for someone to be an excellent coder and a poor tech writer.

I read the essay and all of the posts about it here so far, and my own 
personal opinion is:

1. Everything he said has been said before -- it's basically a rehash of 
old criticisms.

2. My main concern is not with the documentation. My main concern is 
that both the syntax and semantics of the language seem to be more fluid 
than "pragmatic" considerations would dictate. I more or less grew up 
with FORTRAN, although I missed FORTRAN I. So I'll use its evolution as 
an example.

Ten years into its evolution, an ANSI committee was formed to 
standardize the language. Users and vendors sat around a huge table and 
thrashed out what would break the least code, what was easy to 
implement, what kinds of programs people wanted to write in the language 
that they couldn't, etc. The result was FORTRAN 66. 11 years later there 
was FORTRAN 77, etc.

Now FORTRAN is 50 years old, there's a FORTRAN 95 standard, and the 
language is still in use (I think -- I haven't written any since 1990). 
Ruby is a tad older than ten years, and I think maybe it's time for some 
standardization on the syntax and semantics.

I think there are enough "killer apps" now that we know what we can't 
take out of Ruby without breaking Rails, RSpec, Ruport, etc. And from 
MRI, KRI, jRuby and Rubinius, I think we know what's easy to implement 
and what isn't. But what I have no clues about is what programs people 
want to write in Ruby that they can't write now.