From: Dan Debertin <airboss@...>
Date: 2002-09-01T01:36:57+09:00
Subject: Re: suggestions to the Ruby community

I've encountered the same complaints from my co-workers and
colleagues, all of whom came to Ruby from Perl or Python. Many in this
forum have replied to the effect that there is no documentation
problem, and I agree that it's not as bad as most think it is, but as
they say, "where there's smoke, there's fire".

My boss, to give you an example, nearly pulled out his hair trying to
figure out how to use DBI, because he expected documentation to be
someplace obvious, like ./doc/README, not in lib/dbi/doc/DBI_SPEC. My
point being that while, yes, some external packages are simply devoid
of documentation, in many cases what you're seeing is not frustration
at the lack of documentation, but at the lack of consistency with
regard to its location, format and presentation.

The problem, to me, is not that Ruby is particularly bad in the
documentation area, but that its competitors are so much better and
more consistent. I can walk through my entire Perl installation
(containing probably over a hundred modules), and type

% perldoc Date::Manip

or whatever, and get reliably complete information about how to use
the module. 

I was surprised just now to find that there is no absolute requirement
that you have perldoc to post software on CPAN. If it's not a
requirement, it is certainly more deeply ingrained in the Perl culture
than it is in Ruby's. I have _never_ encountered a Perl module that
did not include perldoc. Not even once.


Advantages of perldoc:

o	The format is standard, and looks suspiciously like another
format that at least Unix-users are familiar with (manpage
format). Don't we all immediately lower our opinion of a Unix tool
that doesn't include a manpage? There's a reason -- manpages are quick,
dense and usually complete; if an option isn't in the manpage, it
might as well not exist.

o       To compare to 'ri', it doesn't uselessly reference 
page-numbers in an online resource that is only page-numbered
in the print version. 'ri' also cannot hope to keep up with the rate
of growth the RAA is seeing; it documents the core classes & modules
only. 

o	To compare with 'rdoc' (which, by the way, is valuable in its
own right in that it can extract _some_ documentation from code that
includes none), I for one refuse to switch constantly between Emacs
and a web browser. It's designed for multiple output formats, but the
only one that's implemented is HTML -- and frame-ified HTML, so I
can't just fire up lynx. I like the output, but I would've done
plain-text or *roff before tackling HTML.



With regard to consistency, with Perl (and with Python, I think) there
is _one_ main place to go for documentation (perldoc). It's part of
Perl; no other download is necessary, no web browser is necessary, and
no spelunking into the module's source-tree looking for an elusive
README is necessary. We have ri, rdoc, rdtool, and who knows what
else, not to mention the other 25% of Ruby modules whose documentation
lies in ./README, ./lib/thingy/stuff/USAGE, a remote webpage, some
vague examples under ./example, or is in some cases simply
nonexistent.

I'm not one who usually compaigns _against_ choice, but in this case I
would rather the community just picked one embedded doc format, for
better or worse, bundled it with Ruby, and dropped the rest.


One further point on a completely different tack: pointing back at the
original poster and saying "so fix it!", or just calling them a
useless critic, is a cheap and insulting way to deflect what may be
valuable criticism. 

*dons flame-resistant suit*

Dan
--
/^Dan Debertin$/         
airboss@nodewarrior.org  | Did I sleep a little too late,
www.nodewarrior.org      | or am I awake?        --Byrne