[Python-Dev] status of development documentation

[Fred L. Drake, Jr.]

On Thursday 22 December 2005 08:50, Michael Chermside wrote:
 > Money is not a very effective motivator for this sort of work. (Well,
 > in sufficient quantities it is, but the quantities required are
 > quite large.) Offering *credit* is more effective -- a mention within
 > a contributors list perhaps. 

There is a credits list for the documentation, and it's included in the HTML 
version of the formatted result as well.  Extra credit if you know where it 
is without looking, though.

 > My own favorite idea is to create a comment-on-the-docs mechanism
 > allowing both COMMENTS, and PROPOSED EDITS. The proposed edits would
 > need to be reviewed by one of a small number of skilled and dedicated

I'm unclear on what you buy with having these two labels; are comments things 
that (presumably) get ignored by the documentation editor, or are the 
proposed edits simply more specific?  If the later, I'm not sure having the 
labels helps.

(I'm also concerned that the whole thing could end up being misused as a help 
desk, littering the docs with questions about application problems.)

 > Of course, the person who REALLY gets to decide how it works isn't me;
 > it's whoever decides to spend the time to BUILD this system.

The builder certainly determines what they build, but in the longer term, 
whoever is using it to incorporate changes into the documentation will likely 
have something to say about it, since that's who determines if it actually 
gets used to improve the documentation.


  -Fred

-- 
Fred L. Drake, Jr.   <fdrake at acm.org>