Python docs disappointing

[Emmanuel Surleau]

On Friday 31 July 2009 22:10:45 kj wrote:
> I'm pretty new to Python, and I like a lot overall, but I find the
> documentation for Python rather poor, overall.
>
> I'm sure that Python experts don't have this problem: they have
> internalized some good ways to access the documentation, are
> productive with it, and therefore have lost the ability to see why
> the Python documentations is deficient for beginners.  This explains
> why a suboptimal situation can persist like this: those who are
> most able fix it are also the least able to perceive it.
>
> I've heard similar complaints from other experienced programmers
> who are trying out Python for the first time: poor documentation.

The documentation on python.org is quite extensive. In particular, you may 
want to look at the PEPs, which offer fascinating insights for the reasoning 
behind particular features of Python.

> Here is an *entirely typical* example: on some Unix, try
>
> % pydoc urllib
>
> The displayed documentation mention the optional parameter "data"
> in practically every function listed (a few dozen of them).  This
> parameter is not documented *anywhere* on that page.  All that we
> are told is that its default value is always None.
>
> I'm sure that I can find a full description of this parameter if
> I fire up Google, and search online.  In fact, more likely than
> not, I'll find far more documentation than I want.  But my point
> is that a programmer should not need to do this.  The full
> documentation should be readily accessible directly through a few
> keystrokes.

You have first-grade documentation on the Python website: 
http://docs.python.org/library/urllib.html
I'm not really using pydoc, but I'd wager it's more used as a quick lookup 
than anything else.

> I would love to know how experienced Python programmers quickly
> zero in on the Python documentation they need.

I wouldn't count myself as an 'experienced' Python programmer, but I rely on 
docs.python.org for most things with regards to the standard library.

Cheers,

Emm