improving the Python docs -- a wiki? copy PHP's model?

[Paul Rubin]

comp.lang.python is also a place where you can already most likely
find advice on pretty much any un- or under-documented standard
library module, if you check the archives. So even here we have
everything the PHP docs do.

Is that a joke? Yes, you can sometimes find useful info on Python
topics through Google searches of newsgroup archives, but to say
that's equivalent to PHP's making all the relevant info visible right
there on the doc page for the function you're interested in is
ridiculous. Python users have many good reasons to like Python, but
sometimes they seem to be in denial about areas that could use
improvement.

 

[Follower]

A similar but better solution is to follow the model created by the PHP

community. If you follow the link to
http://us2.php.net/manual/en/function.sort.php you'll see how
impressive the results can be.

I'm surprised no-one has pointed out the Zope documentation system,
which is a little closer to home:

<http://zope.org/Documentation/Books/ZopeBook/2_6Edition/AppendixC.stx>

Comment display can be toggled on & off and the comments are
essentially "inline".

Just another data point.

--Phil.

 

[Skip Montanaro]

Roger> Not only that, there is a many month if not year lead time
Roger> between supplying information via SF and actually having the
Roger> results available (the next release of Python).

Not if you're willing to use the development docs:

http://www.python.org/dev/doc/devel/index.html

Fred updates that at a higher rate than the Python release rate.

Skip

 

[Roger Binns]

Roger> Not only that, there is a many month if not year lead time
Roger> between supplying information via SF and actually having the
Roger> results available (the next release of Python).

Not if you're willing to use the development docs:

http://www.python.org/dev/doc/devel/index.html

Fred updates that at a higher rate than the Python release rate.

Yes, but the whole point of making comments is for the benefit
of other people as well. So unless *everyone* uses the developer
docs, we are back where we started with a many month lead time.

Roger