From: JamesBritt <james@...>
Date: 2002-09-01T16:47:30+09:00
Subject: RE: suggestions to the Ruby community

> (*) Using PHP as a contrasting point again (I have nothing
> against PHP) I think that the PHP docs are more focused
> on a single topic, i.e., web programming. Whereas, Ruby
> is such a capable language and can be applied
> to so many problems, it is unrealistic to expect all areas
> of its application to be fully documented, never-mind the
> excessive documentation that exists with PHP and the web.

It *is* realistic to expect that every class and module in the standard
distribution is documented.

I don't think anyone is looking for cookbook answers before deciding to use
Ruby, but simply the ability to go to one known place and get reasonable,
immediate information about any standard Ruby class or module.  One should
be able to wonder, "Gee, what does Tracer do?", and know exactly where to go
to find out.

>
> (**) I realize that a news group is not a legitimate
> resource for a company...Hey, maybe we should charge companies
> to post questions to ruby-talk. :)


Out of curiosity, I searched ruby-talk, using Google, for tracer, and found
a message asking where to find docs for tracer.rb.  There were no replies.
:(

Anyway, we do need a single standard for writing documentation, and a way to
allow any document, once written, to be exported to any
doc-retrieval/reformatting system (e.g., ri, rdoc, rd,  web site, a
database, or whatever).

James