[Doc-SIG] [Python-Dev] documentation comments
Fred L. Drake, Jr.
fdrake at acm.org
Thu Dec 22 15:16:30 CET 2005
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>
More information about the Doc-SIG
mailing list