Python documentation too difficult for beginners

[Ian]

On 02/11/2010 14:47, jk wrote:
> I think the key difference is that I don't want to have to*read*  the
> python docs - I want to be able to scan for what I'm looking for and
> find it easily. That makes me productive.
Hi jk,

I totally agree. But you will get nowhere.

A few weeks back I complained that
http://docs.python.org/reference/executionmodel.html#naming-and-binding
was more than a little opaque - and was not understood by Python noobs 
such as myself.

I was invited to rewrite it and submit an improved version.

Remember I said I was a noob and did not understand it. Just how can I 
rewrite it from that base?

But I'm sure that the trouble is with me. It is clear from this 
statement (rom that page)...

"If a name binding operation occurs anywhere within a code block, all 
uses of the name within the block are treated as references to the 
current block."

that, (in the given situation), name binding does not bind a name to a 
variable but to a block.
</sarcasm>

Just for the record,  I really know it is not me. English is my mother 
tongue, and I have some programming experience, in a variety of 
languages. I wrote my first program in 1964, and have been earning a 
living programming since '74. I have used Cobol, Lisp, Smalltalk, C, 
Javascript, Notes, PHP and many other languages in a commercial 
environment over the last 36 (good gracious!) years.

This lack of documentation is almost universal. You will have heard of 
the "with batteries" tag. This means that, whatever you want to do, 
there are usually many libraries available to help you do it. Every one 
will be poorly documented and most are hard to find. Yes there are 
batteries - but it is not clear which is more productive: write what is 
needed from scratch, or investigate what "batteries" are available and 
risk finding that the one you chose is missing some important feature 
down the line?

Observe though that having poor introductory documentation sells a lot 
of "How to Program in Python" type books.

Its sad really.  Python is a great little language, and deserves better. 
Without an on-ramp, noobs will struggle to get on the freeway.  And yet, 
enough will get on, that these pleas for better documentation can be 
ignored by those who know and could do something about it.

Regards

Ian

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/python-list/attachments/20101102/adb08537/attachment-0001.html>