From: bbense+comp.lang.ruby.Sep.03.02@... Date: 2002-09-04T03:02:42+09:00 Subject: Re: suggestions to the Ruby community -----BEGIN PGP SIGNED MESSAGE----- In article <87bs7j6l46.wl@discus.nodewarrior.org>, Dan Debertin 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-----