Survey: improving the Python std lib docs

[Terry Reedy]

On 5/13/2017 1:23 PM, jeanbigboute at gmail.com wrote:

> 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.

Thank you for writing a response focused on your experience with the docs.

> 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

The tutorial is meant to be for 'beginners'.

> "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.

When that was likely written, more that two decades ago, python 
beginners were experienced programmers who would have known much of the 
above.  Python beginners today are much different (and even experienced 
programmers are unlikely to know anything about Modula-x.)

If you would like it changed, open an issue on the tracker.

> 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" [remainder of sentence moved below]
> http://cryto.net/~joepie91/blog/2013/02/19/the-python-documentation-is-bad-and-you-should-feel-bad/

This blog post has several sins that you avoided, and did not help to 
improve the docs.  But anyway, to stay on topic...

 > [moved] but has an example at the end of how docs might be rewritten.

The example is a separate page written after the original rant.
http://cryto.net/%7Ejoepie91/walk.html

This example expands 7 lines 6 times to about 42 and in the process 
manages to omit the following important info, which is about 1/5 of the 
original text.

"The visit function may modify names to influence the set of directories 
visited below dirname, e.g. to avoid visiting certain parts of the tree. 
(The object referred to by names must be modified in place, using del or 
slice assignment.)"

I am not sure where it would go in the template.  Templates can be 
straightjackets ;-).

The big issue is examples.  The problem with examples is that they are a 
maintenance burden.  Really.  Without testing, they are not dependable. 
And testing doc examples is not trivial.  So they need to really add value.

There are no examples in the os.path doc, and the particular issue for 
os.path is that results are idiosyncratic to a particular system. For 
some things, like the os.path functions, it is trivial for a user to try 
things out for themselves on their system.  The following took just a 
few minutes.

Python 3.6.1 (v3.6.1:69c0db5, Mar 21 2017, 18:41:36) [MSC v.1900 64 bit 
(AMD64)] on win32
Type "copyright", "credits" or "license()" for more information.
 >>> import sys
 >>> x = sys.executable
 >>> import os.path as op
 >>> op.isfile(x)
True
 >>> op.isdir(x)
False
 >>> x
'C:\\Programs\\Python36\\pythonw.exe'
 >>> op.isabs(x)
True
 >>> op.islink(x)
False
 >>> op.getsize(x)
98968
 >>> op.isdir(op.split(x)[0])
True
 >>> op.splitdrive(x)
('C:', '\\Programs\\Python36\\pythonw.exe')
 >>> op.join(x, 'Lib')
'C:\\Programs\\Python36\\pythonw.exe\\Lib'
 >>> op.isdir(op.join(x, 'Lib'))
False
 >>> op.getmtime(x)
1490136264.0

In any case, besides the tutorial and some of the reference chapters, 
python comes with some 'How-to's with examples.  There are also multiple 
3rd party sites that expand on the docs with examples.  Search 'python 
by example'

-- 
Terry Jan Reedy