From: daniel@... (Daniel Cremer)
Date: 2004-07-06T20:37:40+09:00
Subject: Re: Ruby Advocacy/Documentation/Sponsorship?

> Is there a perception that Ruby still lacks decent documentation? 

I'm still having major problems with the documentation for ruby.  For
example, I've been playing with WEBrick which is now integrated as
standard in Ruby. You would expect such a package to have to be at
least nearly completely documented. Well... have a browse
(http://www.ruby-doc.org/stdlib/libdoc/webrick/rdoc/index.html). I
keep finding myself looking at bits of the source to try to figure out
what a method is for and  if it's the one I'm actually looking for.
This can get especially tedious as Ruby isn't strongly typed so you
need to write code to figure out the class of a returned variable and
track all this in your mind etc... (If I'm being stupid here please
point it out to me! :)).
It just seems to me that this goes totally against the OO design and
advantages of ruby. I know the subject of documentation keeps coming
up here and we like to believe (icluding me) that it's an issue that's
been mostly resolved... but if we really look at how much is missing
from the standard libraries I believe we need to face some facts. If
nothing is done ruby can never live up to it's full potential.
In a bid to not simply complain... (cause we all hate those right ?) I
would have one suggestion. Why don't we make an application so that
people can submit documentation. I believe this is what MonoDoc does
for the Mono project where they have a GUI and a web-based interface
(http://www.mono-project.com/contributing/classlib-doc.html). That way
each time someone plays around with an object or a method they can
just submit some documentation with a short sample of code. With such
a system, and participation of course, the documentation problem could
taken care very quickly.
Has anyone started such a project for ruby before ?  Are there any
gotchas ? I would certainly be interested in giving my time on such a
project... are others interested ?

Daniel

P.S. regarding above, that was not a stab aimed particulary at WEBrick
which is an excellent addition to ruby for which I would like to add
my personal thanks