Re: suggestions to the Ruby community

-----BEGIN PGP SIGNED MESSAGE-----

In article <[e-mail]>,
Dan Debertin  <[e-mail]> wrote:
>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.
>

- - 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. 

- - 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. 

- - 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.

- - 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".

- - 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....  

- - Booker C. Bense

[1]- this is entirely to be expected, after all we are
programmers and earn our livings with the delusion that
if the tool is just good enough the problem will be solved. 

-----BEGIN PGP SIGNATURE-----
Version: 2.6.2

iQCVAwUBPXT2WmTWTAjn5N/lAQGktQP/TaKG4vai/5IKd3jvwATr8/ZpbGdnmSPC
Q7bnuTSJGllnaSaPCMXUPd6ZpB9ka3BQpIN9xwYF2wR0WW45G9ju1xfaxSEid/b9
+glDBaj5iLPQ+ChMOKtkgCgyMEcTs8sjKoVGoXOqTr6oNX48QIHXTb+gGa1petv6
wBASbhbAUoM=
=RVmE
-----END PGP SIGNATURE-----