> >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.
> >
>
> - - You haven't been doing Perl very long then. It took YEARS to
>   get everybody to write perldoc and it didn't really take hold
>   until CPAN was created and perldoc was distributed with the
>   core perl distribution.

Still, hasn't the Perl experience shown that bundling documentation with the
code distribution is a good idea?  Does every language have to go through
the same evolutionary steps?  Can't we have a bit of Lamarckianism?

>
> - - At least in the US Ruby is still in very early development and
>   there are very few people actually working ON it rather than
>   with it. To take examples from the history of Perl, for a very
>   long time the only documentation was the man page. Perl was in
>   use for a long time before the Book[1] appeared. Much like the
>   state of Ruby today. Perl documentation really didn't
>   standardize until the CGI boom of the late 90's. What happened
>   was that being a module author created so much demand for
>   answers, that a standard documentation system was created
>   in self-defense. In the long run it's much easier to write
>   it once than deal with thousands of emails.

Exactly true.  Yet there is the idea that one can just post to ruby-talk as
a substitute for having clear documentation.  Or that leafing through
multiple books is a good way to find out what some method parameter is for.


>
> - - For it's stage Ruby has some pretty amazing online
>   documentation, but it has no real documentors. It has book
>   authors ( which is a very good thing), but nobody committed to
>   the dirty thankless task of documentation management.

Why isn't documentation considered part of coding?  If you write some code
you are (or should be), by definition, its documenter.  I'd be willing to
look after documentation management, but regardless of who does it, it won't
get far unless there is an understanding that, if you write the code, you
have to write the base documentation as well.  Native-language issues aside,
the Ruby culture needs to adopt the Perl culture's attitude towards docs.
There should be an accepted standard for what constitutes minimal
documentation of a lib/class/module, and the tools for using this
documentation should be part of the standard distribution.

The absence of adequate documentation should be considered as much of a
problem as any code bug.

>
> - - Expecting the current developers to take on this project is
>   unrealistic. There have been a couple abortive "Ruby
>   Documentation Projects" already and I suspect we will see
>   a couple more before the demand is truly there. Ruby has
>   it's "Larry Wall", we need a "Tom Christiansen".

I'm unclear why it's unrealistic to expect a developer to write a few
paragraphs of documentation for their own code.  The hard part might be
getting people to translate Japanese to English, and vice versa.  Besides,
writing documentation is a good way to check your own code.  If *you* have a
hard time explaining it in plain language, then maybe there's a problem.

>
> - - IMHO, the Ruby document debate is focused a bit too much on
>   the tools and format[1] and not on the quality and quantity.
>   Rdoc is a great "tool", but it's not documentation. Just
>   write it and worry about the format later....

That's not a bad suggestion, since doc tools without docs are sort of
pointless, but I think writing the docs becomes easier if everyone has a
clear idea what format to use.  But some matters seem as if they should be
fairly simple to resolve.  For example, where does documentation (in *any*
format) go if it's not embedded in the code?  Can we just agree that every
lib distribution has an immediate subdirectory called 'docs', and avoid the
'lib/dbi/doc/DBI_SPEC' problem?

James

>
> - - Booker C. Bense