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 -- https://mail.python.org/mailman/listinfo/python-list
