[Python-Dev] New Pythondoc by effbot

[Guido van Rossum]

On 1/21/06, Terry Reedy <tjreedy at udel.edu> wrote:
> On this page, 8 of 30 entries have a 'new in' comment.  For anyone with no
> interest in the past, these constitute noise.  I wonder if for 3.0, the
> timer can be reset and the docs start clean again.  To keep them backwards
> compatible, they would also have to be littered with 'changed in 3.0' and
> 'deleted in 3.0' entries.  Better, I think, to refer people to the last 2.x
> docs and a separate 2.x/3.0 changes doc.

(That has nothing to do with Fredrik's efforts of course -- he's just
faithfully copying the annotations from the existing docs.)

If Python 3.0 is indeed the major incompatible release that we
currently expect it will be, I agree that "new in 3.0" and "new in
2.x" annotations make little sense, since so much will be "new in 3.0"
(or "deleted in 3.0"). It's probably better to have a separate
document explaining the differences between 2.x and 3.0.

For the 2.x line, however (and again post-3.0) I think the "new in X" 
annotations are important -- lots of people have to deal with
different Python versions, and it's a lot easier to depend on "new in
X" notations than to manually compare two or more versions of the
docs. (Although you still need to do thorough testing -- like the rest
of the docs, these annotations can't be 100% perfect.)

As far as noise goes, "new in X" is minor compared to all the stuff
that's documented that the average user never needs... :-)

--
--Guido van Rossum (home page: http://www.python.org/~guido/)