Do you feel bad because of the Python docs?

[Rotwang]

On 26/02/2013 12:54, Steven D'Aprano 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's no doubt that one of PHP's strengths, perhaps its biggest
> strength, is the good state of documentation. But should we feel bad
> about Python's docs?

I strongly disagree with most of what the author writes. To start with, 
there's this:

   Let’s start out with a simple example. Say you are a developer that
   just started using PHP, and you want to know how to get the current
   length of an array. You fire up a browser and Google for “PHP array
   length site:php.net”. The first result is spot-on, and one minute
   later, you know that count($arr) will suffice.

   Now let’s say that you wish to do the same in Python. In this case,
   you would Google for “Python list length site:docs.python.org”, and
   the first result is… a page with several chapters on standard types?

It seems to me that this is /completely/ the wrong way for a developer 
who's new to Python to go about learning the language. If you don't know 
enough Python to be familiar with len(), the sensible thing to is not to 
try coding by finding out individual language features as and when you 
need them, but to read the tutorial, systematically from start to 
finish. This list is continually being bombarded with questions from 
people who tried the former only to become stuck when something didn't 
work the way they thought it should (I've been guilty of this too), 
because knowing vocabulary is not the same thing as knowing how a 
language works. The majority of such questions could have been answered 
by simply reading the tutorial. More still could be answered by reading 
the language reference, which really isn't very long.

That's not to say that experienced users don't need to look things up, 
but then why would one restrict a web search to docs.python.org? Almost 
every question I've had about how to do something in Python has already 
been asked at StackExchange, and Google will find it.

   When you Google for something, you will end up on a page that
   explains a lot of things, including what you’re looking for. But how
   are you supposed to know where on the page it is, or whether it’s
   even on the page at all? The problem here is that the particular
   operation you are trying to find documentation on, does not have its
   own page.

And the solution is Ctrl-f.

   The general norm for the Python community appears to be that if you
   are not already familiar with the language, you do not deserve help.
   If you do something in a less-than-optimal way, other Python
   developers will shout about how horrible you are without bothering to
   explain much about what you did wrong. When you ask out of curiosity
   how a certain thing works, and that thing is considered a bad
   practice, you will get flamed like there’s no tomorrow – even if you
   had no intention of ever implementing it.

This is not my experience at all. Even when asking questions that I 
could have answered myself if I had RTFM, I've received helpful advice 
and nothing that could be construed as a flame. I don't know how this 
compares to other programming language communities, but it's much 
friendlier to newcomers here than, say, sci.math (whose competent 
regulars are understandably suspicious of people asking idiotic 
questions, given how many of those people turn out to be cranks).

   PHP solves [ambiguity] by having examples for every single function
   and class. If you’re not sure what is meant with a certain sentence in
   the description, you just look at one of the included examples, and
   all ambiguity is removed. It’s immediately obvious how to use things.

Python solves this by having an interactive interpreter. The tutorial 
goes to the trouble of pointing out that "[i]t helps to have a Python 
interpreter handy for hands-on experience".

   If you are an experienced developer, then you are most likely in a
   very bad position to judge how beginner-friendly the documentation
   for a language is.

   [...]

   Most of all, accept that your personal experiences with Python, as an
   experienced developer, are not worth very much. Listen to the newbies
   when they tell you the documentation is hard to read or find stuff in.

But I'm not an experienced developer. I'm an amateur hobbyist who came 
to learn Python having only had any real programming experience with BBC 
BASIC and OPL (both as a child). I read the tutorial, then I read the 
language reference, now I'm reading the library reference. They're all fine.


-- 
I have made a thing that superficially resembles music:

http://soundcloud.com/eroneity/we-berated-our-own-crapiness