[Doc-SIG] [Python-Dev] documentation comments

[Fred L. Drake, Jr.]

On Thursday 22 December 2005 09:22, A.M. Kuchling wrote:
 > 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?  

This was actually a big part of my gardening concern: comments from the 
release X.Y.Z docs need to be handled before releasing X.Y.Z+1 or X.Y+1.*, or 
they aren't being used to improve the documentation at all.

 > (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.)

I'd be more inclined to see that comments are handled (even if handling them 
is a matter of determining that they aren't actually interesting), and just 
toss comments for a new release.  A patch release would be an occaission to 
turn off commenting on the previous releases for the same X.Y version (though 
comments would still exist in the older version).


  -Fred

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