[Doc-SIG] Python manual pages

[Forest]

I'm not sure those extra comments are really needed in Python's case.  I
have used both the Python and the PHP manual quite a bit, and IMHO, the
quality of Python's documentation is much higher.  I almost never need
additional help in order to understand something as documented, and on those
rare occasions when I do, it's almost always something from the standard
library which can be understood by simply looking at the code.  (Remember, a
lot of Python's library is written in Python, installed with Python, and
therefore readily available for examination.)  PHP's docs, on the other
hand, beg for supplemental information because they have so many ambiguities
and omissions.

Moreover, although the user comments in PHP's manual occasionally help, I
find more often that they're misleading and/or encouraging of bad
programming practices.  That's to be expected in a discussion forum, but
when attached to a manual it feels to me like bad advice is being blessed by
the official documentation.  I'd rather have user-submitted comments be
vetted by experts before they get that blessing.  (In fact, this already
happens to some degree.  I remember emailing Guido about a documentation
problem and having a fix appear within a day or two.)

-1  (Nice idea in theory, more harm than good in practice.)


On Fri, 4 Jun 2010 13:39:11 +0200, Jonas Lindberg <badomen02 at gmail.com>
wrote:

>Hi,
>I don't know where to post this to get to the people that has any saying
>about it so I try here =)
>
>Let the community enhance the manual as is done in the PHP manual.
>This is how it looks in PHP manual:
>http://se2.php.net/manual/en/function.ord.php
>
>And here it is in python manual:
>http://docs.python.org/dev/py3k/library/functions.html#ord
>
>As you can see  in the PHP manual there is an example witch is good to have
>in a manual but the best part is that users can comment it and show how to
>use it in "real" code.
>
>This way the makers of the manual pages does not need to do all the work...
>the users contributes and makes it a better manual :)
>
>I really like the Tutorials for Python:
>http://docs.python.org/py3k/tutorial/index.html
>
>But they would also benefit of the possibility to post comments in it :)
>
>Yours, Jonas