Russell Beattie

I've been bitching about this for many years now, but I'm still fascinated at how popular Python is given how insanely user hostile it's library documentation is. I honestly don't know how anyone ever understands how to get anything done beyond a basic for loop, as every time I try to look something specific up, it's either NOT CLEAR or NOT THERE. Don't get me wrong, it's not the core language that's the issue - there's tons and tons of docs about that - from Dive into Python to Guido's original guide itself. That stuff is clear. I'm talking about the standard libraries - what's in them, what they do and how they plug together is a complete mess.

I was playing around with some Python again today (having reversed my previous leaning towards Ruby) and was again amazed that the only way I could get anything done was to do Google searches for random code examples out there in order to understand how various modules and libs plugged together, and even then I relied on IM and IRC as a crutch. So bad... I finally decided to just pick a nice neutral API and explain in detail exactly where the Pythonistas need to improve the docs.

I took a screen shots of part of the DOM API from both the Python and PHP documentation and combined them in the above image to illustrate my point. This is a common interface that's been implemented in various languages so it's a good example to use to show how bad Python's library documentation really is. Here's the PHP Docs and here's the Python docs both for a Dom Node. The differences are staggering.

Here's what PHP's minimal documentation does that Python's just completely doesn't:

* Classes, methods and properties are clearly labeled and separated. Python's listings are just munged together, with properties first and then methods, but without any labels or line breaks telling you about it (you need to look for the parenthesis() to know it's a method).

* The properties in PHP are in a clean, scanable table which give all the basics (object type, read only, description) so I don't have to read paragraphs of text to find what I'm looking for or understand how to use it.

* Contextually, I know I'm working on a DOMDocument because it's repeated over and over again, and I know from scrolling up that same page (which is a mile long, but I don't care because scrolling is fast) how to create that object. Most of the time during development you arrive at some chunk of documentation as the result of a search, having context is key to understanding how to use a particularly lib. Python's docs break the library pages up into unusably small pages that take forever to navigate through, with little context within the pages as well.

* In PHP, the methods are all hot-links with basic descriptions. Clicking them brings you directly to pages with a ton more information about that specific method - including the params I have to pass, whether they are optional or not, and the return value. Additionally there are usually "See Also" methods which may do similar things, but in a different way. Also, the methods all have examples as to how they should be used - usually canonical examples that start with the most basic object that needs to be created before that method can be called, along with the results for various params.

* Each page of PHP's documentation includes a comment section where others can go in and leave examples and links as well. These examples help clarify and expand on the libraries so you can usually copy/paste and get moving to the next thing. If some library or method isn't particularly well documented, many times the comments pick up the slack admirably.

Python's library documentation is just text. No links, few tables, non-standard ways of describing params and return values, little in the way of showing you how objects thread together, and NO EXAMPLES AT ALL. There's no reason for it - it's all simply about organization and clarity. For a group of people who extol the virtues of their language as being so clean and easy to read, it's amazing how little thought they give to this sort of basic and fundamental language feature.

Every single Pythonista will bitch about how "ugly" PHP is, but you know what? PHP's docs make learning a new API and getting code written so much more easy that it doesn't matter how fugly the end result is. If I come back to that code and wonder WTF is going on (which has happened) I can just go back to the docs and re-learn quickly and easily so it doesn't matter. Honestly, if Python had library documentation with similar quality it'd probably be the number one scripting language, hands down. If only those guys would get a clue about this stuff really.

-Russ