Python Documentation (should be better?)

[Skip Montanaro]

    Christopher> The intricacies of the computing term "greedy" aside, yes I
    Christopher> think the Python documentation should generally be better.
    Christopher> What that means, I have no idea.  All I know is that I like
    Christopher> PHP's documentation and it should be like that.

It would help if you could narrow the scope down a bit. ;-)  Can you spend a
little time comparing and contrasting the online Python and PHP docs and
make some specific comments?

    Christopher> My question is, why is PHP's documentation so good and
    Christopher> Python's mediocre?

I don't think it's so much that Python's documentation is mediocre.  I think
most of what you need is there (I count about 110k lines of LaTeX source
split over a hald dozen chunks of documentation).  It may be that it's not
all that well organized for online searching/contribution/annotation.  It's
more book-like.  That may be largely due to the fact that it's written in
LaTeX which doesn't lend itself well to a highly interactive end result.

Google helps.  If you search for the terms you're interested in at
http://docs.python.org/ your search will be restricted to the official
online docs.  That might help a bit.  Also, I find the module index to be
the most useful bit of documentation to have handy:

    http://docs.python.org/lib/modindex.html

    Christopher> Does it have to do with corporate backing (I have no idea
    Christopher> if PHP is or not, I'm just saying)?  The quality/quantity
    Christopher> of volunteers?  The design of the language itself?

There does seem to be a very high ratio of people who complain about the
documentation to people who write the documentation.  Many of us with little
time but a modicum of LaTeX knowledge are willing to mark up plain text
patches to the documentation.

If you're interested in seeing what's going in in the Python documentation
world, browse the doc-sig's archives:

    http://mail.python.org/pipermail/doc-sig/

Skip