On 5/13/2017 1:23 PM, jeanbigbo...@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
--
https://mail.python.org/mailman/listinfo/python-list
