Do you feel bad because of the Python docs?

[Chris Angelico]

On Tue, Feb 26, 2013 at 11:54 PM, Steven D'Aprano
<steve+comp.lang.python at pearwood.info> wrote:
> One week ago, "JoePie91" wrote a blog post challenging the Python
> community and the state of Python documentation, titled:
>
> "The Python documentation is bad, and you should feel bad".
>
> http://joepie91.wordpress.com/2013/02/19/the-python-documentation-is-bad-
> and-you-should-feel-bad/
>
> It is valuable to contrast and compare the PHP and Python docs:
>
> http://php.net/manual/en/index.php
> http://www.python.org/doc/

There are some issues with the Googleability of the Python docs at the
moment. It's much easier to find the official page of PHP's docs than
Python's. Trouble is, the official page of PHP docs is a lot less
helpful... like he says, it's in some cases flat-out wrong. And then
you go read the comments underneath in the hope of learning what you
need to know... and you find a pile of junk even worse than the main
docs, but with the occasional useful gem so you can't dismiss it out
of hand. (But it's buried among loads of code whose primary purpose is
to explain why there's so much bad PHP code out there.)

His "experiment" (name all the possible error conditions) is one that
I guarantee you will fail in EVERY language. Even in Java, where a
method has to declare every exception it might throw, makes an
exception (if you'll excuse the pun) for "runtime errors"... such as
division by zero. So if I write a function that takes two arguments,
divides one by the other, and adds three, then I don't need to declare
that it might bomb if you give it zero and zero. Will it be in the
docs? Unlikely.

The lack of examples is a valid concern. However, PHP isn't actually
that much better, because the prolific examples don't always help.
Examples are no panacea.

Final point: "NO-ONE IS FIXING THIS". I wonder how many docs patches
he's submitted, how many newbies he's courteously and competently
assisted.

The complaints about the community definitely do not apply to
python-list. So I'd say that's a fairly good fallback: if you can't
find what you need in the docs, and you've made a genuine effort to do
so, ask on c.l.p/p-l and you'll likely get a response within a day -
sometimes within the hour. (If Giacomo says he will respond within the
hour, he will respond... within the hour!)

tl;dr: Nothing's perfect but it ain't as bad as all tharrt.

ChrisA