Re: suggestions to the Ruby community

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

In article <[e-mail]>,
JamesBritt <[e-mail]> 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-----