Re: Linux is not for consumers!
On Thursday 11 December 2003 04:58 pm, s. keeling wrote:
> Incoming from Richard Kimber:
> > Aren't you missing the point that you need to understand it before you can
> > document it, and that in many cases understanding does not come without
> > documentation.
>
> If you need to understand it to use it, you've got the source. What
> more could you need? That's not good enough? Don't use it. You
> think it would be better with good documentation? Great. Go write
> some. Oh, you want me to write some? Why? I don't think it needs
> it since I have no trouble using it.
This defensive attitude is common, but not universal amongst
developers. I actually like writing documentation for stuff I write. It
often starts before the code does (but that usually means it
needs to be revised a lot).
Saying that the source code *is* the documentation is not unlike
saying the Human Genome is an Anatomy & Physiology textbook.
:-P
I feel that good documentation (not to mention accurate spelling
and grammar, etc) is an important craftsmanship issue, and I don't
like to short-change it. I don't know how many times I've gone
through my code just to fix the bad spelling in comment lines. The
most embarrassing thing was when I had to change the API to
my Zope product because I misspelled a word in a function name!
That was really dumb.
> The LDP is always looking for volunteers. Hint, hint. The common
> sense answer to this whole thread is, "Don't look a gift horse in the
> mouth."
At one level, you're right -- no one has a right to force you to
write documentation if you don't want to. Nor to space and
indent your code so other programmers can read it. Nor to
use variable names that are remotely related to the things they
represent.
That doesn't make obfuscation a good practice. And it's good
practice that's being discussed here -- which is entirely appropriate
for discussion, IMHO. I for one, like to keep improving at what
I do.
The service-bureau management model is highly flawed for
many applications. Given a complete failure of the embedded
approach, we turn to it as a last resort. Don't confuse that with
success.
That's like saying that having a fire department justifies
sub-standard wiring.
The people who know a program best are the ones who work
on its internals. No one else can write documentation like the
guy who built the thing in the first place. Failing that, you can
have someone step in and write it, yes. But it'll never be as
accurate as you'd like, nor as up-to-date.
The ideal, for me, is to include documentation within the program
in a literate-programming style, and generate the documentation
from the code. This solves the other bad problem with Free
Software documentation -- being WRONG. Wrong documentation
can be worse than none!
(With specific reference to Zope and Python code, this seems to
be the biggest problem from my POV).
IMHO, good documentation means more people using, testing,
and (perhaps ultimately) contributing to my project. For those of
us for whom those are principle motivators for releasing the
code under a free-license in the first place, that's more than
enough reason to make documentation part of the task.
I also like to write documentation because I have a crummy
memory. I write documentation so *I* can use it, too. :-) In fact
I just spent all day yesterday reading one of my own manuals.
OTOH, when I first released the program, I thought it was so
simple that it didn't need documentation. But some of the
people on the mailing list I announced to suggested that it
really did. In retrospect, I can certainly see that they were
right.
I like Python for that, because there's so many great introspection
tools built into it (I was never able to get anywhere with the
original cweb literate programming system).
Of course, I come from an academic background, so
writing has always been part of my job.
Anyway, I just wanted to point out that we're not all such
curmudgeons about writing. :-D
To the O.P. though -- bear in mind when you make this kind of
criticism that you are criticizing somebody's baby. They do tend
to get quite defensive. It takes a lot of confidence in yourself to
accept criticism of your work without feeling personally attacked. ;-)
One thing you get with free-licensed open source software that
you don't get with the proprietary beast *is* actual contact with
the author. That's unheard of for proprietary stuff!
Cheers,
Terry
--
Terry Hancock ( hancock at anansispaceworks.com )
Anansi Spaceworks http://www.anansispaceworks.com
Reply to: