The Python documentation is bad | Hacker News Reader

The Python documentation is bad

joepie91.wordpress.com

9 pointsjoepie9110 comments

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.

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

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

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

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.

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

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

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

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.

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.

Reply on news.ycombinator.com