From: Marcelo <marcelo.magallon@...>
Date: 2011-08-06T05:42:57+09:00
Subject: Re: Brainstorming ideas how to improve Ruby's documentation

On Fri, Aug 5, 2011 at 02:48, Marc Heiler <shevegen@linuxmail.org> wrote:

> We need NEW ideas and for this to happen some OLD ideas must die.

Agree on the general point.

I think you are using the wrong reference, though.

If you want to compare to an excellent documentation implementation,
look at Perl.

Perl's killer feature is its documentation, IMO.

$ perldoc POSIX
$ perldoc LWP
$ perldoc Test::More
$ perldoc -f print
$ perldoc -f open
$ perldoc perlre
$ perldoc perllol

And so on...

(For those among you cringing at the idea of a command line, there are
web pages with this, e.g.

http://perldoc.perl.org/
http://perldoc.perl.org/POSIX.html
http://perldoc.perl.org/Test/More.html
http://perldoc.perl.org/perlre.html
http://search.cpan.org/~mschwern/Test-Simple-0.98/lib/Test/More.pm)

I think there are two sides to this:

1. Perl's community has a tradition of NOT documenting isolated
functions, but documenting modules.  I guess you could fix this by
providing better tools.

2. Perl's community appreciates Perl's documentation a lot, so module
authors do write good documentation.  This needs a change in attitude.

Marcelo