From badomen02 at gmail.com  Fri Jun  4 13:39:11 2010
From: badomen02 at gmail.com (Jonas Lindberg)
Date: Fri, 4 Jun 2010 13:39:11 +0200
Subject: [Doc-SIG] Python manual pages
Message-ID: <AANLkTilCXYPmKECpJdTkY6tPyQIv49iTS1Ewg1O6viMj@mail.gmail.com>

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>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/doc-sig/attachments/20100604/a9ccfbd3/attachment.html>

From list8a.forest at tibit.com  Sat Jun  5 19:36:32 2010
From: list8a.forest at tibit.com (Forest)
Date: Sat, 05 Jun 2010 10:36:32 -0700
Subject: [Doc-SIG] Python manual pages
In-Reply-To: <t41l06daaeg4q0fofrv014jqmn7p5620sc@4ax.com>
References: <mailman.6.1275732002.23803.doc-sig@python.org>
	<t41l06daaeg4q0fofrv014jqmn7p5620sc@4ax.com>
Message-ID: <3m2l0659thloef9hrl67cltvb6ci1auu6n@4ax.com>

>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

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

P.P.S.  Sorry for top-posting earlier.  :)

From list8a.forest at tibit.com  Sat Jun  5 19:33:29 2010
From: list8a.forest at tibit.com (Forest)
Date: Sat, 05 Jun 2010 10:33:29 -0700
Subject: [Doc-SIG] Python manual pages
In-Reply-To: <mailman.6.1275732002.23803.doc-sig@python.org>
References: <mailman.6.1275732002.23803.doc-sig@python.org>
Message-ID: <t41l06daaeg4q0fofrv014jqmn7p5620sc@4ax.com>

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