[Python-Dev] status of development documentation (original) (raw)

Fred L. Drake, Jr. fdrake at acm.org
Thu Dec 22 15:26:55 CET 2005

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.

More information about the Python-Dev mailing list