From: Matt Gushee <mgushee@...>
Date: 2002-09-05T05:00:46+09:00
Subject: Re: suggestions to the Ruby community

On Thu, Sep 05, 2002 at 04:25:10AM +0900, bbense+comp.lang.ruby.Sep.04.02@telemark.stanford.edu wrote:

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

And there's always a danger of the embedded documentation getting out of
sync with the code.

On the other hand, I'm not sure that 'let coders code, and writers
write' is always a good solution either. *If* you have sufficient
resources to support separate people writing code and documentation,
*and* the organizational culture is such that developers and writers can
adequately communicate, that division of labor can produce good results.
Yet there's an awful lot of bad software documentation out there, and a
good portion of it is written by professional writers who seem to have a 
poor understanding of the product they're writing about. And there are
many situations (e.g. sole contractor gigs and small-to-medium open
source projects) where there simply isn't a tech writer available.

And the idea that programmers can't write is a stereotype. I know
at least half a dozen programmers who are excellent writers. Writing 
inspiring prose may be a rare gift, but any intelligent adult should 
be capable of writing clear descriptions and instructions if they set 
their mind to it. With sufficient peer pressure, more people might do
just that.

As for the problem of things being 'obvious', the solution to that is
feedback. Bugs in the documentation? Submit a bug report.

-- 
Matt Gushee
Englewood, Colorado, USA
mgushee@havenrock.com
http://www.havenrock.com/