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

[Stephen J. Turnbull]

>>>>> "David" == David A Cobb <address@hidden> writes:

    David> Stephen J. Turnbull wrote:

    >> Footnotes: [1] Note also that Debian goes to extreme lengths to
    >> insure cooperation of packages it distributes among themselves,

    David> Um, you aren't saying this is a bad thing, are you Stephen?

No.  Merely that Debian users are highly unlikely to pose the kinds of
problems that I'm thinking about when I write "nightmare".  This
serves Debian's purposes well, but among Linux and *BSD distros, it
_is_ extreme.

    David> However a volunteer project likely can't take _extreme_ measures.

Debian can and does (the Emacs Policy), as does the GNU Project (the
FSF assignment policy[1]).  The question is do the benefits justify the
discouragement of contributions?  And that largely depends on the
contributors' perception of need for the measures.

The problem with more strict documentation requirements is not that
programmers see no need for documentation, or even no need for user-
level documentation.  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.
It certainly could be done by users (a) with only limited amounts of
time or (b) with only limited acquaintence with the implementation.

And one of the most frustrating things for any maintainer is a post of
the form "it took me two hours to figure out how to do X, but I
finally did.  No thanks to the crummy docs!"  And no thanks to you,
either, for not telling us what you learned....  Users have a lot of
information that the maintainers do not know.  Aggregating that would
be very useful, but how?  FAQs are traditional, of course, and Wikis a
more modern route.  But these tend to take on a life of their own, and
not get integrated into the distributed manuals and other docs.

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.


Footnotes: 
[1]  "Extremism in the defense of freedom is no vice."  By the test of
comparison with other projects, it is nonetheless extreme.

-- 
Institute of Policy and Planning Sciences     http://turnbull.sk.tsukuba.ac.jp
University of Tsukuba                    Tennodai 1-1-1 Tsukuba 305-8573 JAPAN
 My nostalgia for Icon makes me forget about any of the bad things.  I don't
have much nostalgia for Perl, so its faults I remember.  Scott Gilbert c.l.py