From: bbense+comp.lang.ruby.Sep.04.02@... Date: 2002-09-05T04:25:10+09:00 Subject: Re: suggestions to the Ruby community -----BEGIN PGP SIGNED MESSAGE----- In article , JamesBritt wrote: >> >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? > - - I think it's a good idea, particularly in a language as readable as Ruby. I'm just trying to introduce a bit of scale into the problem. As I see it, there are a lot of people complaining and very few doing. It won't just happen overnight. Standards are nice, but usable standards require a tremendous amount of work. To continue your biology metaphor "ontogeny recapitulates phylogeny" Every language needs to go through the stages, it's just a question of how fast. I think Ruby could go through this stage fairly quickly, but I don't expect to see a standard document format until at least a year after raa.succ ( whatever that turns out to be ) is well in place. >> >> - - 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. > - - Well, that works fine until you reach a certain scale of use. IMHO, the demand for perl-style documentation is getting the horse in front of the cart. There is a chicken and egg problem here, once consensus is reached then most people will fall in line, but people are reluctant to put much effort into documentation until consensus is reached. > >> >> - - For it's stage Ruby has some pretty amazing online >> documentation, but it has no real documenters. 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. - - In practice this almost never works. Writing good code and writing good documentation are separate skills. Even if you can write documentation as the code's author, you often have many things that are "just obvious" that you never even think to document. > 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. > - - In my experience, when you start saying "should" in the open source world you're generally wasting your time. I don't think you'll get any real disagreement with the above statement, the problem is picking the standard. >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. > - - If it was this simple, it would already be done. Documenting the Ruby core has already be done once, the problem is integrating that in such a way as to keep it current. The standard library has never been documented in this fashion. >> >> - - 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? - - These are not "fairly simple to resolve", they are exceedingly complex and require a lot of community thrashing and competition between competing ideas/models before consensus is reached. Standards emerge from the documentation, documentation does not emerge from standards. I'm not saying we should not tackle these problems, I'm saying it's a lot more complicated that most people seem to think. - - Booker C. Bense -----BEGIN PGP SIGNATURE----- Version: 2.6.2 iQCVAwUBPXZZNmTWTAjn5N/lAQFmuwQAq/siC4e2Q+FgDlsC1gzWQkQyzbESQiIx iTwvit06vfQE3Peoc3b/u7vV70sZyDxcyRY5BB4ZeFLHYOyrCaCdcfMTAcU7JIR8 ewsEt0iK1mQpiC9zG+QOgjaFe0VgFuF4UvaPQZWKsvGAXCvEASEW2+rRWaZJm3vw dvNCg1683PI= =RITQ -----END PGP SIGNATURE-----