Python manual pages

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
3 messages Options
Reply | Threaded
Open this post in threaded view
|

Python manual pages

Jonas Lindberg
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
--

"The true delight is in the finding out rather than in the knowing."
- Isaac Asimov


_______________________________________________
Doc-SIG maillist  -  [hidden email]
http://mail.python.org/mailman/listinfo/doc-sig
Reply | Threaded
Open this post in threaded view
|

Re: Python manual pages

Forest-39
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 <[hidden email]>
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
_______________________________________________
Doc-SIG maillist  -  [hidden email]
http://mail.python.org/mailman/listinfo/doc-sig
Reply | Threaded
Open this post in threaded view
|

Re: Python manual pages

Forest-39
>On Fri, 4 Jun 2010 13:39:11 +0200, Jonas Lindberg <[hidden email]>
>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

P.S.  You found the right place.  This is where we discuss Python
documentation issues.

P.P.S.  Sorry for top-posting earlier.  :)
_______________________________________________
Doc-SIG maillist  -  [hidden email]
http://mail.python.org/mailman/listinfo/doc-sig