Doc-SIG

Download

doc-sig@python.org

June 2010

2 participants
2 discussions

Re: [Doc-SIG] Python manual pages
by Forest June 5, 2010

June 5, 2010

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(a)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

1 1

Python manual pages
by Jonas Lindberg June 4, 2010

June 4, 2010

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 [image: Close] Read more >> Options >> [image: Visit Answers.com] <http://www.answers.com?initiator=FFANS>

1 0