
The Python documentation is bad - joepie91
http://joepie91.wordpress.com/2013/02/19/the-python-documentation-is-bad-and-you-should-feel-bad/
======
pekk
Yet another PHP programmer throwing a tantrum about Python is neither
representative nor particularly instructive.

There is no technical substance in this criticism, so it is really useless for
anything except venting about one person's tastes.

~~~
Camillo
I much prefer Python to PHP, but I think you're being unfair. He makes some
good points.

------
warmfuzzykitten
Stop being defensive. He has a point. Python docs can be frustrating. Too many
times, docs lead with examples instead of a simple list of functions or
methods accompanied by examples. It's true the function/method descriptions
are often incomplete; some argument description are only hints, exceptions
thrown are rarely stated, etc.

He's wrong about getting questions answered. Don't know about the Python
community, but the StackOverflow community (and elsewhere) more than makes up
for it. It's very rare that I haven't gotten a good answer to a question in
the first one or two google responses. Where the author went wrong is trying
to outsmart google by directing the query to a particular set of documents,
instead of just asking, e.g., 'python length of array'.

~~~
joepie91
I have updated the post to explicitly exclude Reddit and StackOverflow, as
these two sites have a very particular and curious community atmosphere that
doesn't accurately reflect the general atmosphere in more Python-focused
communities.

As for your point regarding the search query: I normally do not filter search
results by domain. The reason I filtered them here, was because the article
was about the official Python documentation. To quote my elaboration on this
that I posted on the Reddit thread:

"My point was that the official Python documentation is poor. I certainly
agree that many things are answered on StackOverflow, but imagine that you're
looking for something that not very many people use. You'll search on Google,
not find any StackOverflow posts (after all, nearly noone uses the thing
you're looking for), and you just find a few unclear blog posts and a Python
documentation page.

Official documentation is important especially as a fallback when other
sources fail to provide the relevant information. As such, the focus of the
official documentation should be on complete and clear, unambiguous reference.
That's not what the official Python documentation provides.

While len() may be a very simple example (and intentionally chosen for that
reason), I've more than once run across things for which basically no
documentation could be found aside from an ambiguous explanation in the Python
documentation that never got me anywhere."

(source:
[http://www.reddit.com/r/Python/comments/18ssb6/the_python_do...](http://www.reddit.com/r/Python/comments/18ssb6/the_python_documentation_is_bad_and_you_should/c8hu26i))

------
saundby
Pretty well captures my experience, though there's a lot to like about Python,
it's 3rd parties that are making it accessible in spite of what's at
python.org. Also, the CP4E concept is regularly decried as defunct and
unworkable in Python forums.

------
Socketubs
Python documentation is perfect for me. I love to have examples, more friendly
comments about "methods", "objects", etc...

Php documentation just looks like a code parsing vomit with very poor Css...

------
bsg75
Maybe the PHP docs are better, but for me the Python docs are good enough, and
I will take Python the language any day.

------
alexrson
The python documentation is adequate. The only thing I think it needs is more
example code.

~~~
jlgaddis
I've started learning Python just within the last month and I agree.
Obviously, I need explanations of how things work but to then see a few basic
examples really helps solidify things for me.

------
jlgaddis
I'm not a "developer" or "programmer" by trade, like many of you here on HN
are. In the last 15 years, I've been a Windows admin, a Linux admin, a
security guy, and a networking guy. For the last several years, I have been
almost exclusively managing Linux servers and networking gear (primarily Cisco
and HP).

For background, I started out learning 6502 assembly at a very early age
(which I've long since forgotten), Commodore BASIC, GW-BASIC, QuickBASIC,
Turbo Pascal, and then onto Perl and, later, "enough" PHP to make some basic
web apps. I wouldn't consider myself even close to being an "intermediate"
level programmer.

After being introduced to Linux in the mid-90s, I began learning Perl
(primarily to write CGI scripts). I've wrote a few small applications in PHP
over the years but most of the code I've written has been Perl. Also, probably
95% of the code I have written is stuff that helps me do my job quicker,
easier, or more efficiently (in other words, I'm not really developing
applications for the "public" or anyone else, only for myself).

I recently decided I wanted to learn Python, but following examples or
tutorials has never really "done it" for me as I quickly get bored. I've had
much better luck by finding an existing problem I need to solve and then
diving straight in and learning what I need to as I go along.

That's what I did with Python. A month ago, I knew absolutely nothing about
it. I watched most of the videos on Youtube from Google's Python class (which
is awesome, by the way) and worked through a lot of the exercises. Shortly
afterwards, I found a real-world problem (at $work) that needed to be solved
and, although I could have knocked it out fairly quickly with Perl, I decided
to make this my Python learning exercise.

In the last two weeks, I've went from only knowing the very basics to a
complete solution. Looking back at my code now, it parses command-line
arguments, interacts with the user (to obtain a router password), uses SNMP to
gather a bunch of data from an access point (this is a WISP environment, not
your typical SOHO AP), connects to a Cisco router and makes a bunch of
changes. SNMP, MySQL, regular expressions, working with files, lists, hash
tables ("dicts"?), etc. It's not the most complex piece of code ever written
but it's certainly well past the "Hello, world" difficulty level.

As you might guess, I performed a fair number of Google searches during the
time I was writing my program. I didn't come across anything that I
wanted/needed to do that I wasn't able to. Perhaps the documentation on
docs.python.org isn't 100% complete or the best, I don't know, but I do know
that I managed to figure out how to do everything I needed to, almost entirely
from the results returned in my Google searches.

The author may be right about the state of the documentation on docs.p.o but,
overall, I think it's irrelevant. There is sufficient documentation "out
there" in the whole of the "world wide web" that any newbie to Python (myself
included) can quickly learn anything about Python that they want to.

