[Top][All Lists]
[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.
.
- Re: INFO on add-ons, (continued)
- Re: INFO on add-ons, Stephen J. Turnbull, 2002/09/01
- Re: INFO on add-ons, Miles Bader, 2002/09/01
- Re: INFO on add-ons, Stephen J. Turnbull, 2002/09/02
- Re: INFO on add-ons, Miles Bader, 2002/09/02
- Re: INFO on add-ons, Stephen J. Turnbull, 2002/09/02
- Re: INFO on add-ons, David A. Cobb, 2002/09/02
- "Extreme Documentation" [was: INFO on add-ons], Stephen J. Turnbull, 2002/09/03
- Re: "Extreme Documentation" [was: INFO on add-ons],
David A. Cobb <=
- Re: "Extreme Documentation" [was: INFO on add-ons], Thien-Thi Nguyen, 2002/09/03
- Re: "Extreme Documentation" [was: INFO on add-ons], Stephen J. Turnbull, 2002/09/03
- Re: "Extreme Documentation" [was: INFO on add-ons], Thien-Thi Nguyen, 2002/09/04
- Re: INFO on add-ons, Richard Stallman, 2002/09/03
- Re: INFO on add-ons, Stephen J. Turnbull, 2002/09/03
- Re: INFO on add-ons, Robert J. Chassell, 2002/09/03
- Re: INFO on add-ons, Henrik Enberg, 2002/09/03
- Re: INFO on add-ons, Miles Bader, 2002/09/03
- Re: INFO on add-ons, Kai Großjohann, 2002/09/03
- Re: INFO on add-ons, Kai Großjohann, 2002/09/03