Do you feel bad because of the Python docs?

[Steven D'Aprano]

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 don't think that either the Python documentation
or community is as bad as JoePie91 suggests. (Well, I won't speak for the
people on Freenode's #python. It took me approximately three minutes to
be banned from there, with no warning or explanation.)

Another response to the blog post, by one of the core developers:

http://blog.briancurtin.com/posts/why-i-dont-feel-so-bad.html

 

[Chris Angelico]

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

 

[Roy Smith]

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.)

Having lived through a year of PHP hell, I've developed a theory about
the PHP ecosystem (i.e. docs, forums, user community, etc) vs. the
Python ecosystem.

When people ask PHP questions, the questions tend to be phrased as "what
do I type to get X", and the answers come back that way too. The forums
are full of, "I had the same problem. Somebody told me to do this. I
don't really understand it, but it worked for me and maybe it'll work
for you too".

The Python ecosystem is much more about understanding what's actually
happening.

 

[Zero Piraeus]

:

One week ago, "JoePie91" wrote a blog post challenging the Python
community and the state of Python documentation [...]

[...] should we feel bad about Python's docs?

The Python docs are my first port of call when I know the module (and
maybe the function) I want to use, but can't remember exactly how it
works. For that, and for me, they're very good.

I can also usually find the section I want if I'm answering a beginner
question on Stack Overflow and want to provide an explanatory link,
but if I weren't already familiar with the docs, I think it's quite
unlikely I'd find the relevant page easily. I agree with joepie91 that
the information on fundamental stuff is poorly organised.

I don't think that either the Python documentation
or community is as bad as JoePie91 suggests.

I think he has a point, albeit exaggerated, regarding the community -
or at least python-list, which is the part with which I'm familiar.
This list can be a little imposing for beginners, and its habit of
veering away from the original question into an esoteric discussion of
the language, while entertaining and educational to read for *me*,
might well end up causing OP to scratch their head.

I don't think it's intended, but sometimes there's also the sense that
regulars here are trying, not entirely successfully, to hide their
impatience with simple questions. I don't hang out at python-tutor, so
maybe it's better there (in which case, maybe its existence needs to
be better advertised).

I think Stack Overflow is a little better at that, possibly because
the rep system there encourages "grinding" in the MMORPG sense, and
easy questions get a bunch of people piling on with answers almost
instantaneously.

-[]z.

 

[Chris Angelico]

When people ask PHP questions, the questions tend to be phrased as "what
do I type to get X", and the answers come back that way too. The forums
are full of, "I had the same problem. Somebody told me to do this. I
don't really understand it, but it worked for me and maybe it'll work
for you too".

A problem that's majorly exacerbated by the myriad ways of doing some
things, with some of those ways deprecated and others theoretically
plausible but hopelessly impractical.

Here's an actual example that came up today at work. Suppose you have
a user-provided string that's supposed to contain a URL, and you need
to ensure that it doesn't have a trailing slash, so you can later add
"/foo" or "/bar". (Or alternatively, ensure that it DOES have a
trailing slash. Either works.) Start the timer, go find out how to do
it. Assume you are broadly familiar with PHP, and know how to do the
basics of string handling, and are competent at searching the web.
Ready? Go!

I'll wait for you to come back.

.... Okay, some of you are back now. Just giving the stragglers time to
finish losing their marbles...

Alright. Here's what I found in a recreation of today's search.
Google search: php last character of string

http://php.net/manual/en/function.substr.php
-- okay, so I can use substr, but not string indexing, to find out
what the last character is
-- "Returns the extracted part of string; or FALSE on failure, or an
empty string." What kind of failures result in FALSE, and what kind in
an empty string?

http://stackoverflow.com/questions/4427172/find-last-character-in-a-string-in-php
Comment on question: "There are more than 10 ways of doing this!"
The accepted answer, fortunately, is a good one. Use rtrim. Okay.
That's nice. But look at the other answers: one mentions substr (as
above, that's half the question); one suggests the unwieldy form of
indexing from the back (with an explicit strlen); one answers
altogether the wrong question (suggesting the use of basename); and
one... suggests a regular expression. Now you have two problems.

And just to add to the pile of ways this could be done, the first
response in this thread
https://forums.digitalpoint.com/threads/how-to-get-last-character-in-string.796134/
suggests *reversing the string* and indexing from the front.

Maybe you tried different search terms and got better results, I don't
know. This wasn't the only search I did in trying to find the best way
to do this, but it was the one with the most amusing results.

The original rant specifically excluded sites like Stack Overflow as
valid sources, which in a way is fair enough. But it wasn't from
php.net that I got that information.

Okay. Now I'll try it again, for Python.
Google search: python last character of string
First result:
3.1.2 Strings
docs.python.org/release/1.5.1p1/tut/strings.html
Besides numbers, Python can also manipulate strings, which can be
expressed ... word[-1] # The last character 'A' >>> word[-2] # The
last-but-one character 'p' ...

The use of code with directly connected comments means that I can read
this part of the solution right there, without even clicking the link.
Search Engine Optimization FTW.

Searching for the second part, by adding the word 'remove' to the
search, brings up more third-party sites - for PHP:
http://www.if-not-true-then-false.com/2010/php-remove-last-character-from-string/
and for Python:
https://groups.google.com/forum/?fromgroups#!topic/comp.lang.python/TIX5u3Zhikc
http://stackoverflow.com/questions/9639754/python-remove-last-char-from-string-and-return-it

In both cases, answering the question, but not from the language's own
site. Forcing the matter with a site: search brings up poor results
for both languages. Python gives me:
http://docs.python.org/release/2.6/library/string.html
but nothing about slicing. PHP: Take your pick of functions, and I
hope you already know what they do, because the snippets don't help
you choose:
substr, rtrim, chop (which, once you go to the page, reveals itself to
be an alias for rtrim), strrpos, substr_replace, strstr

I'd have to say that, in the shoot-out, both languages died on their
own merits, but stood on the merits of third-party support. Fifteen
years ago, I would have called that a critical failure; in the 90s, I
would search for information only from official sources. But these
days, forum archives and blogs are some of the best way to find what
you need - granted, Sturgeon's Law applies, but frankly that applies
to a lot of documentation too (and Google's fairly good at helping you
find the 10%).

ChrisA

 

[Steven D'Aprano]

And just to add to the pile of ways this could be done, the first
response in this thread
https://forums.digitalpoint.com/threads/how-to-get-last-character-in- string.796134/
suggests *reversing the string* and indexing from the front.

Oooh, deja vu! It's like it's 1988 and I'm learning to program in
Hypertalk all over again!

 

[notbob]

"The Python documentation is bad, and you should feel bad".

Ahh! A point at which I can interject.

As a rank green python noob, I definitely hava an opinion on python
documentation and it's not entirely flattering. OTOH, it's hard to
toss any other single linux based documentation up as a sterling
example. IOW, I've seen worse. How am I learning about python?

Several sources. The "Non-Programmer's Tutorial" docs from wikibooks
was a false start. It goes for about 2 pages before I realized
they've snuck in some python syntax without explaining it. So, I jump
over to "The Python Tutorial", which immediately leaves me submerged,
as it's waaay over my clueless head. I flounder around and
desperately grab onto "Basic Python" over at About.com. Finally, I'm
rescued!

Whoda thunk it? I usta despise About.com. But, they've matured
greatly since their early days. I'm not a programmer. In fact I
really dislike programming. But, as a long time linux user, I really
need to learn a useful higher language. And here is this website that
takes me by the hand and speaks to me like what I am. Dumb as a post
and disinterested. But, they are patient. They explain basic
programming concepts before launching into specifics. When they do
get specific, they use simple examples that make sense. The don't
toss in syntax they haven't fully explained. Great site and the one
I'm now using to progress. I'm sure the other sites I've named will
become helpful, eventually, but now I can move forward with
confidence.

Are python doc sites perfect? No. I've yet to come upon anything
that clarifies why's and wherefores and the differences between the CMI
IDLE and the GUI IDLE. And boy, are they different! OTOH, as I said,
I've seen worse Linux docs. BitchX or zsh? What docs!? Even the man
pages took me a long time to figure out. Bluefish? Krita?
Puh-leeze! emacs? It's a wonder I can use it at all.

Despite all that, I'd say python documentation is better than a poke
in the eye with a sharp stick. I'm sure the official pages will make
more sense to me when I understand more. As it is, they jes toss out
"lc-letter" like I know what they're talking about. They explain it a
little bit, but I still hadda wiki it to get the full story.

As a person with some technical writing experience, I know how
difficult it can be. I had to be careful about who I was writing for,
engineers or laymen. It's the same with programming docs. Writing
tutorials about python as if I jes came from 5 yrs as a C programmer
is not in the least bit helpful to a beginner like myself. Sometimes,
one jes hasta hunt for the right flavor.

nb

 

[Adam W.]

I think learning a language from the documentation is an unreasonable expectation and burden for the authors.

Buy a book, take a class, they are designed to provide you with a path from start to finish in a sensible manner, the documentation in my opinion is supposed to be a reference and a refresher with an assumed level of basic fundamentals.

I'm currently taking a class in ARM assembly, the notion that I should expect to plop the thousand+ page reference manual on my desk and just "get to it" is absurd.

 

[Andrew Berg]

zsh? What docs!?

You mean other than the gigantic user manual?
http://zsh.sourceforge.net/Doc/

 

[MRAB]

A problem that's majorly exacerbated by the myriad ways of doing some
things, with some of those ways deprecated and others theoretically
plausible but hopelessly impractical.

Here's an actual example that came up today at work. Suppose you have
a user-provided string that's supposed to contain a URL, and you need
to ensure that it doesn't have a trailing slash, so you can later add
"/foo" or "/bar". (Or alternatively, ensure that it DOES have a
trailing slash. Either works.) Start the timer, go find out how to do
it. Assume you are broadly familiar with PHP, and know how to do the
basics of string handling, and are competent at searching the web.
Ready? Go!

I'll wait for you to come back.

... Okay, some of you are back now. Just giving the stragglers time to
finish losing their marbles...

Alright. Here's what I found in a recreation of today's search.
Google search: php last character of string

http://php.net/manual/en/function.substr.php
-- okay, so I can use substr, but not string indexing, to find out
what the last character is
-- "Returns the extracted part of string; or FALSE on failure, or an
empty string." What kind of failures result in FALSE, and what kind in
an empty string?

[snip]
The page http://php.net/manual/en/function.substr.php says:

Description
string substr ( string $string , int $start [, int $length ] )

OK. It then goes on to say:

Parameters
string
The input string. Must be one character or longer.

What? The input string can't be an empty string?

 

[notbob]

You mean other than the gigantic user manual?
http://zsh.sourceforge.net/Doc/

"This document was generated by Simon Ruderich on July 24, 2012"

.....'bout damn time!!

nb

 

[Tim Chase]

"This document was generated by Simon Ruderich on July 24, 2012"

....'bout damn time!!

Generated...from source that has been around for ages:

http://zsh.git.sourceforge.net/git/...d3b0506f99e690f521d9bf449dea47a51502cb2;pg=11

which suggests that they've been actively maintained since 1999-2000
or so.

-tkc

 

[notbob]

which suggests that they've been actively maintained since 1999-2000
or so.

.....in various guises, dating back to the man pages. Not all as
thorough as the latest "manual". Perhaps I shoulda qualified usable
docs.

nb

 

[Terry Reedy]

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/

To me, this is a lying troll rant worth less than most of RantingRick's
posts.

It is valuable to contrast and compare the PHP and Python docs:

http://php.net/manual/en/index.php
http://www.python.org/doc/

The contrast has been discussed before on python-list and even pydev. To
repeat: in my opinion, and that of most core developers, the python docs
are superior. It is Joe's lie to equate difference of opinion with
indifference.

Python has a nice Tutorial for beginners. It is an integral part of the
doc set. To ignore that (and the indexes) in discussing the usability of
Python docs by beginners is to lie. (If beginners who actually read the
tutorial have problems with particular paragraphs, improvements can be
and have been made.)

Examples: Once startup is explained, the rest of the tutorial is about
half text and half example. I think that is a good balance. Anyone who
reads the tutorial knows how to call a function. I think doubling the
size of the Library *Reference* with trivial, repetitive examples like:

len([1,2,3])

3

would be a negative for reference use*. Python has a super-duper
interactive mode for trying things like this oneself, and that teaches
*better* than just reading the same thing. (And if the tutorial never
discusses len() and its generic use for all concrete collections, it
should.)

* Anyone who disagrees can go to
http://www.lightbird.net/py-by-example/builtin-functions.html
where you can find that and other examples for builtins and about 30
modules. Actually, I can imagine that some beginners would benefit from
this page as an extension of the tutorial. This site may be an outcome
of the previous discussion, which more or less ended with the fact that
anyone who wanted to produce php-style Python docs was free to do so.

Searching: it is true that the Python docs are written for being read by
people, rather than by search engines#. It has a hand-crafted index
(yes, it still needs patches) that will get you most places, especially
for anyone who has read the tutorial to get the basics. For 'length of a
list' one can find 'len() (built-in function)' and find that 'len'
indeed mean length and, more generally, size.

# Anyone who wants to could develop an seo-optimized python-by-function
website that goes into exquisite details for each function on a separate
page.

len(collection) => count
Built-in function len() allows one to find the
* length or size of a list
* length or size of a tuple
* length or size of an array
* length or size of a string
* length or size of a bytes
* length or size of a bytearray
* length or size of a memoryview
* size of a set
* size of a frozenset
* size of a dict or dictionary
* size of dict view
* size of user-defined collecton class instances

Returns 0 for empty collections. Raises TypeError for inputs that are
not collections or that do not support len() calls, because they do not
have a properly written .__len__ methods.

If I were involved, I would *not* junk-up such pages with random user
posts. Anything worth being added should be incorporated into the entry
itself.

 

[Devin Jeanpierre]

I think learning a language from the documentation is an unreasonable expectation and burden for the authors.

That's how I learned it. The Python tutorial, together with the stdlib
reference manual, are often recommended to beginners to Python in
order to learn it. The combination of the documentation and consulting
other programmers helped me learn the language just fine.

Buy a book, take a class, they are designed to provide you with a path from start to finish in a sensible manner, the documentation in my opinion is supposed to be a reference and a refresher with an assumed level of basic fundamentals.

I would assert it isn't very kind to those even with basic fundamentals.

For example, under precisely what circumstances does int() raise
TypeError? You won't find that under either int's documentation, or
TypeError's documentation, you have to look it up under __int__, which
is _not_ a basic fundamental. And rather than helping you along the
way, the documentation for int() actively misleads you by its
implicature that the only acceptable types are strings, ints, and
floats. And then even if you have the foresight to remember "oh yeah,
isn't there a special method for this?", you have to find the
documentation for __int__, which is itself is three quarters of the
way down this massive page:
http://docs.python.org/2/reference/datamodel.html .

-- Devin

 

[Mitya Sirenef]

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 don't think that either the Python documentation
or community is as bad as JoePie91 suggests. (Well, I won't speak for the
people on Freenode's #python. It took me approximately three minutes to
be banned from there, with no warning or explanation.)

Another response to the blog post, by one of the core developers:

http://blog.briancurtin.com/posts/why-i-dont-feel-so-bad.html

I think the issue with python documentation is that it ignores the 95/5
rule: 95% of people who land on a module's page are only looking for 5%
of its information. So ideally it'd be separated in two different pages
or two sections of the same page, something like:

===============================================================================================

Hi, chances are you are the 95% of people who isn't interested in the
intricacies, obscure edge cases et cetera. Here are the few common use
cases for this module:

....

....

....

===============================================================================================

Hi, the section above obviously did not suit your needs, so you must be
in the 5% who has no choice but to either read through or at least
glance through, or use search, to find what you need in the following
umpteen million of screenfuls:

.... * 1000000


===============================================================================================

Why doesn't Python do that? Quite simply, it's a lot more work: you have
to separate most useful parts from the rest, which involves judgement
calls and will cause some disagreement and ultimately won't be perfect.
Once done, two separate sections need to be mainained and kept in sync.
It's important that they don't contradict each other.

Right now places like SO and mailing list act like the first section I
described. The issue is that they're not always up to date and not
guaranteed to be correct, are not in a consistent style and depth, are
not centralized.

-m

 

[nn]

Ahh!  A point at which I can interject.

As a rank green python noob, I definitely hava an opinion on python
documentation and it's not entirely flattering.  OTOH, it's hard to
toss any other single linux based documentation up as a sterling
example.  IOW, I've seen worse.  How am I learning about python?

Several sources.  The "Non-Programmer's Tutorial" docs from wikibooks
was a false start.  It goes for about 2 pages before I realized
they've snuck in some python syntax without explaining it.  So, I jump
over to "The Python Tutorial", which immediately leaves me submerged,
as it's waaay over my clueless head.  I flounder around and
desperately grab onto "Basic Python" over at About.com.  Finally, I'm
rescued!

Whoda thunk it?  I usta despise About.com.  But, they've matured
greatly since their early days.  I'm not a programmer.  In fact I
really dislike programming.  But, as a long time linux user, I really
need to learn a useful higher language.  And here is this website that
takes me by the hand and speaks to me like what I am.  Dumb as a post
and disinterested.  But, they are patient.  They explain basic
programming concepts before launching into specifics.  When they do
get specific, they use simple examples that make sense.  The don't
toss in syntax they haven't fully explained.  Great site and the one
I'm now using to progress.  I'm sure the other sites I've named will
become helpful, eventually, but now I can move forward with
confidence.

Are python doc sites perfect?  No.  I've yet to come upon anything
that clarifies why's and wherefores and the differences between the CMI
IDLE and the GUI IDLE.  And boy, are they different!  OTOH, as I said,
I've seen worse Linux docs.  BitchX or zsh?  What docs!?  Even the man
pages took me a long time to figure out.  Bluefish?  Krita?
Puh-leeze!  emacs?  It's a wonder I can use it at all.  

Despite all that, I'd say python documentation is better than a poke
in the eye with a sharp stick.  I'm sure the official pages will make
more sense to me when I understand more.  As it is, they jes toss out
"lc-letter" like I know what they're talking about.  They explain it a
little bit, but I still hadda wiki it to get the full story.

As a person with some technical writing experience, I know how
difficult it can be.  I had to be careful about who I was writing for,
engineers or laymen.  It's the same with programming docs.  Writing
tutorials about python as if I jes came from 5 yrs as a C programmer
is not in the least bit helpful to a beginner like myself.  Sometimes,
one jes hasta hunt for the right flavor.

nb

For me on the other hand. The Python tutorial has been the most useful
tutorial I have ever used. I had experience with Basic and Pascal.
Most other tutorials go too slow for me and I loose interest. The
python one just kept going and after reading the dozen pages in a
couple of hours I had enough of an idea about the language to start
doing the things I was interested in.

The only thing that confused me at first was finding functions like
"open" or "input" and string methods. I lost a bit of time searching
in the language reference until I found out that they are in the
Library reference: I didn't think of "open" as a library. But now I
have no problem; all I need is found under Library reference in
section 2 and 4 and starting with section 6. I also use the global
module index when I already have an idea what I am looking for.

What it could have is better searching capability and a way to see
more examples. Examples would clutter the documentation so maybe they
should be collapsible, but you can never have enough examples. As
Einstein said:
“Example isn't another way to teach, it is the only way to teach”
Outside of the tutorial there are not a lot of succinct examples of
more advanced uses of the different keywords and builtins. Thankfully
for the libraries there is Python Module of the Week for people that
know about it.

 

[rh]

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".

No I do not feel bad.
I did not read the post either.

As a newcomer to python I found the docs to be difficult.
I'm getting used to reading them after a few months.
Any document is written for some audience, maybe
python needs to target wider audience groups. One for programmers
from other languages (maybe one for each major language?).
One for those new to programming and python at the same time.
One for python programmers (have mostly that now, I think)
Etc.

If I harken back to those days when I first used man pages
it was a moment of "Wow! This is great!" followed by many
moments of "Hmmmm, do they mean this...?".

Incorrect docs are worse than none. I think most of the python docs
I've read have been correct although sometimes stuff is just missing.
Like threading.local was not easy to find.

HTMLParser is avoided by lots of people because it requires lots
of prior knowledge.

Examples are worth more then plain old doc.

 

[Rotwang]

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 sitehp.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 "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.

 

[Jason Swails]

Just to throw in my 2c -- in the same way that 'a picture is worth a
thousand words', an interactive interpreter is worth volumes of
documentation (especially one with such a nice help()/__doc__
functionality). It's worth pointing out that 'interpreter' appears in the
original rant once (according to ctrl-F, whole thing was tl;dr):

Want to know how the Python interpreter deals with input Y? Read the
source. And so on, and so on.

Not: "Open up an interpreter and input Y"

You aren't sure what errors are thrown by a particular function? Fire up
an interpreter and feed the function junk. You'll get your answer faster
than you can Google, and often learn neat stuff along the way. (I recall
one of RR's posts that actually had some good tips to
learn-via-interpreter).

Also, I'll bet the way I learned Python effectively would seem like
nails-on-a-chalkboard to others -- and vice versa. The 'one-size-fits-all'
doesn't work for documentation. Complete and concise often battle, with no
clear winner.

And his representation of the Python community does not appear to be
representative of my experience (threads begun via trolling rants
notwithstanding). But he's ranting on his blog; not a big deal really.

--Jason