emacs-devel
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: "Extreme Documentation" [was: INFO on add-ons]


From: David A. Cobb
Subject: Re: "Extreme Documentation" [was: INFO on add-ons]
Date: Tue, 03 Sep 2002 11:49:26 -0400
User-agent: Mozilla/5.0 (Windows; U; Windows NT 5.0; en-US; rv:1.1b) Gecko/20020829

Stephen J. Turnbull wrote:

"David" == David A Cobb <address@hidden> writes:
The problem is that most of it is already
available in docstrings, so that creation of reasonably complete
functional documentation _could_ (at least in theory) be automated.

Yeah, I thought of that. Needs to bubble around a bit in my head before speaking.

It certainly could be done by users (a) with only limited amounts of
time or (b) with only limited acquaintence with the implementation.

F'rinstance: I have huge quantities of time available and I'm a better than average wordsmith. Getting organized is a problem, and misleading documentation is worse than none at all.

These alternative means of generating documentation undermine the
perception of need for documentation by the programmers themselves.
So it's hard to generate a consensus for a draconian docs policy.  Nor
does "encouragement" work well; programmers, with much justification,
feel that their code contributions deserve weight and that they are
already contributing sufficiently to documentation.

Now that's just sad.
--

David A. Cobb, Software Engineer, Public Access Advocate
"By God's Grace I am a Christian man, by my actions a great sinner." -- The Way 
of a Pilgrim; R. M. French, tr.
Life is too short to tolerate crappy software.
.






reply via email to

[Prev in Thread] Current Thread [Next in Thread]