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
--
http://mail.python.org/mailman/listinfo/python-list
