From: Jim Freeze <jim@...>
Date: 2002-09-01T15:18:53+09:00
Subject: Re: suggestions to the Ruby community

I recently gave a presentation at work on Ruby
and overall it was well received. I got a big
reaction when I demonstrated rdoc (something
I didn't really expect). The ability to have
documentation automatically generated was a big
deal for them. I also showed ri and irb. They liked
the online ri and asked if classes that
we write can be included into ri. (I have heard
talk of this but don't know the status). I also
showed the 6 or so books that are out on Ruby.

There were no comments about lacking documentation,
not to say that there won't in the future. My personal
experience is that the documentation is out there,
but it is not as easy to find, as say PHP documentation.(*)
Also, I find that for the real tough questions, I 
use ruby-talk. And for the most part it is a very
reliable resource.(**)

After reading others comments on this issue, I have
been able to form a loose collection of requirements 
I would like to see.

1) Ruby libraries and apps should have a standard documentation markup.
2) The documentation should have a standard location (file or directory)
   and should take into account localization.(***)
3) Any raa (or raa.succ) submittal should require a minimum
   amount of existing documentation.
4) A standard documentation tool should be part of the install
   and provide translation of documentation markup into man
   and html formats (don't know if a std exists on windows/mac).
   A real bonus would be to provide print documentation
   as well.
   Note: this does not limit other docy systems, but establishes 
   a minimum doc system which all are guaranteed to have.
5) A commandline driven online doc system should be part of the 
   install (ri or like ri).
6) A user should be able to add their own generated library documents
   to the online doc system.

(It's late, so I may have missed a few, so please feel free
to add or modify this list.)

Using ri, rdoc and simple markup, the foundation for these requirements
already exist and have been proven to some extent. If a
standard can be agreed upon, I think that this little bit of structure
can go a long way.

One last point, I find the reactions of some of these companies
quite interesting when they say there is insufficient documentation.
I don't remember ever reading about a standardized documentation
system for C or C++. And when I was using the stdc++ library,
it was never considered that the couple of books that existed
were insuffient and there should be online docs with cookbook
recipes for me before my company would begin using it.


(*) 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.

(**) 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. :)

(***)It is a bit much to expect developers to provide translation,
but if the documentation can be put in an html format, then
there are plenty of online web page translators.
I think most other languages just assume that you have to know English.

-- 
Jim Freeze
If only I had something clever to say for my comment...
~