Do you feel bad because of the Python docs?

[Terry Reedy]

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