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
--
http://mail.python.org/mailman/listinfo/python-list
