[Python-Dev] documentation comments

[A.M. Kuchling]

On Thu, Dec 22, 2005 at 09:27:06AM +0000, Steve Holden wrote:
> Could the PSF help here by offering annual prizes for the best 
> contributions to the documentation, or wouldn't that be an adequate 
> motivator?

I think the most effective thing would be to award a grant to someone
to build a real comment-on-the-docs system.  There were a few Summer
of Code proposals for this sort of thing; one was funded but the
developer decided to do a KDE project instead.  

I had lunch with Fred the other day, and he was worried about whether
anyone would garden the comments to remove spam.  That is indeed an
issue, but I think we can cope with that problem once a system is
built.

Another worry is versioning.  Once lots of people have made comments
on Python 2.4.0's documentation, what do you do when 2.4.1 is
released?  Do you move the comments to the new docs, or leave them
attached to 2.4.0 and start 2.4.1 with a clean slate?  (Perhaps the
system could work a little like a bug tracking system; comments could
be marked as 'applied', and applied comments don't get moved from
2.4.0 to 2.4.1 because their content is now in the docs.)

--amk