On Tue, Feb 26, 2013 at 11:54 PM, Steven D'Aprano <steve+comp.lang.pyt...@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 -- http://mail.python.org/mailman/listinfo/python-list
