Survey: improving the Python std lib docs

[jeanbigboute at gmail.com]

On Friday, May 12, 2017 at 3:02:58 AM UTC-7, Steve D'Aprano wrote:
> One of the more controversial aspects of the Python ecosystem is the Python
> docs. Some people love them, and some people hate them and describe them as
> horrible.
> 
> Here are a couple of suggestions for improving(?) the docs. What do you
> think?
>

.............[ deletia ].............

Thank you for bringing up this important topic.  As an occasional Python user, I find that Python documentation is all over the usability map - some great, some difficult.  The Python docs have been at best a starting point.  I usually need to go to other sites like this group, StackOverflow, and a blog or two to understand how to do something.  After I learn to do that one thing, I am not any more independent, self-reliant, or able to contribute back to the community.  Although Matlab gets a lot of grief in the open source community, its documentation is concise, complete, and self-contained.  

A table of functions/classes at the start of a Python doc would be very helpful.  I'd also like to see a tree-like overview of a package so I can get an idea of what's available and how deep the dot-indexed hierarchy goes.  I've tried to write code to extract/present this for myself and have failed.  IDEs and Notebooks allow descending a branch one dot at a time - very time consuming.  

Many of the docs go deep into CS terminology from the start which can be daunting. Here's the first paragraph from the 'Classes' documentation:
https://docs.python.org/2/tutorial/classes.html

"Compared with other programming languages, Python’s class mechanism adds classes with a minimum of new syntax and semantics. It is a mixture of the class mechanisms found in C++ and Modula-3. Python classes provide all the standard features of Object Oriented Programming: the class inheritance mechanism allows multiple base classes, a derived class can override any methods of its base class or classes, and a method can call the method of a base class with the same name."

I am sure it is all correct.  I just don't know what it means.  

I saw pkgutil referenced in answers to some StackOverflow questions and I looked into it:

https://docs.python.org/2/library/pkgutil.html

"This module provides utilities for the import system, in particular package support."

Then it gets very specialized.  

I am well aware of the distinction between documentation and tutorials. I think that the Python docs of today are too close to research articles and the specialized knowledge that implies.

This blog post is "in-the-face" but has an example at the end of how docs might be rewritten.

http://cryto.net/~joepie91/blog/2013/02/19/the-python-documentation-is-bad-and-you-should-feel-bad/

--- JBB