On 2/26/2013 7:54 AM, Steven D'Aprano wrote:
One week ago, "JoePie91" wrote a blog post challenging the Python
community and the state of Python documentation, titled:
"The Python documentation is bad, and you should feel bad".
http://joepie91.wordpress.com/2013/02/19/the-python-documentation-is-bad-
and-you-should-feel-bad/
To me, this is a lying troll rant worth less than most of RantingRick's
posts.
It is valuable to contrast and compare the PHP and Python docs:
http://php.net/manual/en/index.php
http://www.python.org/doc/
The contrast has been discussed before on python-list and even pydev. To
repeat: in my opinion, and that of most core developers, the python docs
are superior. It is Joe's lie to equate difference of opinion with
indifference.
Python has a nice Tutorial for beginners. It is an integral part of the
doc set. To ignore that (and the indexes) in discussing the usability of
Python docs by beginners is to lie. (If beginners who actually read the
tutorial have problems with particular paragraphs, improvements can be
and have been made.)
Examples: Once startup is explained, the rest of the tutorial is about
half text and half example. I think that is a good balance. Anyone who
reads the tutorial knows how to call a function. I think doubling the
size of the Library *Reference* with trivial, repetitive examples like:
>>> len([1,2,3])
3
would be a negative for reference use*. Python has a super-duper
interactive mode for trying things like this oneself, and that teaches
*better* than just reading the same thing. (And if the tutorial never
discusses len() and its generic use for all concrete collections, it
should.)
* Anyone who disagrees can go to
http://www.lightbird.net/py-by-example/builtin-functions.html
where you can find that and other examples for builtins and about 30
modules. Actually, I can imagine that some beginners would benefit from
this page as an extension of the tutorial. This site may be an outcome
of the previous discussion, which more or less ended with the fact that
anyone who wanted to produce php-style Python docs was free to do so.
Searching: it is true that the Python docs are written for being read by
people, rather than by search engines#. It has a hand-crafted index
(yes, it still needs patches) that will get you most places, especially
for anyone who has read the tutorial to get the basics. For 'length of a
list' one can find 'len() (built-in function)' and find that 'len'
indeed mean length and, more generally, size.
# Anyone who wants to could develop an seo-optimized python-by-function
website that goes into exquisite details for each function on a separate
page.
len(collection) => count
Built-in function len() allows one to find the
* length or size of a list
* length or size of a tuple
* length or size of an array
* length or size of a string
* length or size of a bytes
* length or size of a bytearray
* length or size of a memoryview
* size of a set
* size of a frozenset
* size of a dict or dictionary
* size of dict view
* size of user-defined collecton class instances
Returns 0 for empty collections. Raises TypeError for inputs that are
not collections or that do not support len() calls, because they do not
have a properly written .__len__ methods.
If I were involved, I would *not* junk-up such pages with random user
posts. Anything worth being added should be incorporated into the entry
itself.
--
Terry Jan Reedy
--
http://mail.python.org/mailman/listinfo/python-list
