[Python-Dev] status of development documentation

[Michael Chermside]

Steve Holden writes:
> Could the PSF help here by offering annual prizes for the best
> contributions to the documentation, or wouldn't that be an adequate
> motivator?

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. Even more effective is offering the
chance to make a difference: immediate feedback (seeing your edit in
place). Thus, I'm a big fan of amk's suggestion:

> I think the most effective thing would be [...]
> to build a real comment-on-the-docs system.

But I agree strongly with Fred's concerns:
> he was worried about whether
> anyone would garden the comments to remove spam.

and as Michael Hudson put it:
> Writing good documentation is hard.
>
> And sometimes the problem is that the document isn't really structured
> right, or it has been hastily updated to cover too many changes that
> it's a dogs breakfast, or some other 'global' problem and these
> *really* take time to fix.

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
editors (Fred Drake... you're a hero!) before being officially
incorporated. That's not all that different from the current system
(submit a patch to sourceforge), except that the format for entering
the change would be simpler.

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.

-- Michael Chermside