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

Search Discussions

  • Forest at Jun 5, 2010 at 5:33 pm
    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 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
  • Forest at Jun 5, 2010 at 5:36 pm

    On Fri, 4 Jun 2010 13:39:11 +0200, Jonas Lindberg 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. :)

Related Discussions

Discussion Navigation
viewthread | post
Discussion Overview
groupdoc-sig @
categoriespython
postedJun 4, '10 at 11:39a
activeJun 5, '10 at 5:36p
posts3
users2
websitepython.org

2 users in discussion

Forest: 2 posts Jonas Lindberg: 1 post

People

Translate

site design / logo © 2018 Grokbase