From: gsm.beamon / gmail.com [mailto:gsm.beamon / gmail.com] 
> As such, Ruby designers might have more carefully considered how'd
> they expect programmers to understand Ruby libraries for that's how
> Ruby development of Ruby programs would proceed.

I 100% agree, and I think it applies more generally than just Rails. To
restate what you're saying, documentation is MORE important in Ruby than
other languages, because runtime shenanigans and dynamic typing make it
hard(er) for a documentation tool to figure out what's going on and
provide useful feedback.

Documentation in general has been one of Ruby's sore points for a long
time (though getting better all the time thanks to many dedicated
volunteers). For example, look at the number of libraries included with
the Ruby Standard Library[1] that are listed in italics[2]. The XSD
library, for instance, looks like it might be quite useful...but I have
no idea because all that exists are the standard documents.


> I will stop here. I don't want to say more or less. I don't want to
> start discussing dynamic v. static typed languages either. 
> All I have done is identify a single area of Ruby which requires
> some continuous improvement. In working with Ruby and Rails for about
> one week in some detail, this is the only serious qualm I have.

And even though I don't work with rails much, in general I want to thank
you for your persistence in stressing this problem. It's very difficult
for any who have worked with something for a moderate amount of time to
see it with fresh eyes. Explicit mentions of all irritations encountered
when first playing with Ruby are, in some cases, the only way the
problem will get noticed and possibly corrected.

"Misfit provides an incentive to change; good fit provides none."[3]
Even if you don't propose a solution to the problem, or intend to act
upon it yourself, it's helpful to know what's bothering you. (Who knows
how many others may be similarly bothered.)


That said...if you DO want the problem solved soon, you may take it upon
yourself to keep track of each documentation flaw you find and either
contact the code maintainers, or fix the problem yourself and submit a
patch. Many hands make light work, and all that.


[1] http://www.ruby-doc.org/stdlib/
[2] indicating less-than-ideal documentation
[3] http://phrogz.net/nodes/criticismwithoutasolution.asp