RE: suggestions to the Ruby community

> -----Original Message-----
> From: [e-mail]
> [mailto:[e-mail]]
> Sent: Wednesday, September 04, 2002 12:25 PM
> To: ruby-talk ML
> Subject: Re: suggestions to the Ruby community
>
> JamesBritt <[e-mail]> wrote:
> >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.

I don't see people complaining, I see people questioning, or raising
concerns, or thinking out loud, or any number of things.  I don't think you
intended to be pejorative, but it is not uncommon on this and other lists
for some people to label certain discussions as "complaining", or
"bickering", or "whining", with the result of discouraging people from
speaking up.  ("Complaining", "bickering", etc. seem to be defined as
"prolonged discussion on something one has now decided to stop
considering.")

It is entirely possible to see a problem but not have a solution, yet some
prefer that nobody speak up unless they can propose an alternative.  (And
then, when they do, they are told that they should go implement it since
they thought of it.)

OK, end of rant.

There are some discussions that, ultimately, do not have a software
solution.  They deal more with the underlying principles and philosophy of
the community.  They may not converge on a solution in one or two days.
Matters of documentation may fall into that category.  Code runs whether you
have comments or not, so who cares, right?  What constitutes "appropriate"
documentation is quite subjective.  "Official" documentation standards or
not, what will ultimately drive the creation and maintenance of good, useful
documentation are community values.


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

I mentioned Lamarckianism because I view the biology metaphor as deeply
suspect.
Some people seem to take it on faith that language development must follow
some Darwinian, evolutionary processes, but we are not dealing with biology.
We have the advantage of extreme hindsight, and the divine ability to
manipulate things at will. Every language need not go through the same
stages.

Conceivably, Matz could just mandate some feature that dictated the path of
Ruby documention.  This is unlikley, but ultimately there needs to be an
explicit guiding hand.  Relying on some sort of marketplace of competing
formats, styles, and philosophies of documentation, wherein most of the
mistakes of the past are repeated, before electing a format, seems
needlessly expensive.

There is another thread right now concerning Java and Ruby, and while I
don't greatly care for Sun or Java, Java has a big advantage in that Sun is
quite happy to mandate certain features, such as JavaDoc.  Its discouraging
to think that a standard Ruby API doc format won't occur until a year after
some unknown time in the future.

Right now, Ruby has RD (a markup language), and RDoc (a tool for extracting
and formatting salient code features and comments).   RDoc and rdtool should
be part of the base distribution.  Essential documentation for the core
classes should be with the source code, and updated as the source is
updated.  Docs can be generated whenever a you grab a new release.  Minimal
documentation should include what the class or module is for, what each
method is for, what each method parameter is for.

We might look at the Sun's "Requirements for Writing Java API
Specifications"
(http://java.sun.com/j2se/javadoc/writingapispecs/index.html) as a
guideline.

We should ask, what's the cost of selecting a possibly sub-optimal API
documentation standard now, versus the cost of waiting until one emerges a
year after RAA.next, while further adoption of Ruby is dampened by the lack
of complete documentation.


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

That scale of use won't happen if people find it too hard to locate complete
class and library help.  I define "too hard" as having to look in more than
one place.  Many people have decided they like Ruby, and have stuck with it
long enough to figure out all the places to dig when trying to learn the
language.  Others, though, have walked away because this is just too much of
an investment.   For the former, the various workarounds adopted in lieu of
complete API documentation have become second nature, so that when somebody
such as stibbs suggests this is a real problem, people act puzzled.

Ruby itself wins over hackers and language fans, but persuading management
is a bit harder.
(Kent Starr expressed it quite well in [ruby-talk 49040].)

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

People don't omit documentation because they don't know what style to use;
they omit it because they know they will not get any flack.   Many of the
Java developers I worked with never bothered to write even basic JavaDoc
comments, and it wasn't because they were ignorant of JavaDoc.  It was
because they could wave their hands and tell people "read the source", and
people considered that acceptable geek machismo.  Later, these same people
wondered why management wanted to drop the custom code and go with an
off-the-shelf, fully documented product.


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

That someone isn't as good at writing docs as writing code shouldn't excuse
anyone from writing docs.  Besides, "skill to do comes from doing."  I also
agree with Matt Gushee's comments in [ruby-talk 49021].  It would be nice to
have the appropriate division of labor, but in the meantime, software
developers need to write.

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

I know, it's sort of like saying, "Somebody should take out the garbage."
By and large, open-source software (OSS) developers produce those things
they enjoy doing, which often overlaps with those things other people want
or need.  But it's the gaps and omissions that discredit much OSS in the
eyes of many looking for professional-grade tools.  There isn't always
somebody taking out the garbage.


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

Resolving every aspect of a uniform documentation process may be complex.
Where to place the docs in a library distribution is not.


James



>
> - - Booker C. Bense