Re: Some more? (was: Re: My Best Ruby Documentation Suggestion)

On 8/22/05, Alexander Kellett <[email protected]> wrote:
> On Aug 22, 2005, at 3:55 AM, Sy wrote:
> > I would disagree in that comments still have to be integrated into an
> > article, creating an overhead as compared to entirely user-editable
> > material.
> 
> imo this overhead is a needed evil in order to keep documents in a
> unified style.

Coming from a wiki background, I'd disagree with the need for this
"style" stuff.. but the ruby docs are not like a wiki and you're
right, they'd be required to have a certain kind of style.  Random
users cannot easily be held to a style, unless the open editing of the
documentation managed that somehow.  i.e. some kind of very-templated
and shaped editing process.


> > But for something like library docs (as opposed to
> > user-documentation).. yeah, I see how basic commenting would be the
> > obvious step to take.
> 
> the utility of the community comments on php.net alone should be
> enough evidence of this :)

To be honest.. I'm dismayed at the continued existance of comments
where the comments themselves can become as or even more valuable than
the documentation they are speaking on.

There needs to be very serious effort to absorb and then delete
comments, so that the articles become the canonical thing to read.

This is where slashdot falls flat on its face.  Comments are utterly
worthless unless absorbed into the greater topic, unless the reader
reads through the many threads of discussion.  This presents one voice
for for a passer-by to read, and it removes the wasted efforts of
people repeatedly commenting the same thing over and over.

Now, of course Ruby's docs won't have the kind of activity that
slashdot posts have, so there's less conern.. but looking at the
ruby-talk list, there is a lot of discussion which might leak into the
documentation commenting-medium.


Argh, I'm going on..  I'm sure I'll be happy with whatever's presented.  =)