Survey: improving the Python std lib docs

[jeanbigboute at gmail.com]

On Saturday, May 13, 2017 at 3:39:52 PM UTC-7, Terry Reedy wrote:
> 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.

... [ trimmed ] ...

I appreciate your prompt reply.  I would like to 'aggregate' my thoughts along a couple of items you mentioned.

1) Old documentation (e.g. Classes referencing Modula-3) and opening trackers.

The Classes and Pkgutil docs are representative of a lot of the Python docs that fall into the hard-to-use category.  I would have to file many trackers to cover problems I have had.  That's not very grateful in context of an open source tool.  Discussing this at a top-level as we are doing here I think is fair game.  This is something that needs to be addressed comprehensively or possibly intentionally left alone.

If the original doc suite was written 20 years ago, it may not be possible or practical to get it caught up when the language evolves so quickly.  
The right answer might be to "leave it be" and accept that newer methods of Q&A have to take over.  This is true even of some paid packages - to get help with Microsoft, avoid the documentation wherever possible.  This approach has its problems especially for corporate users.  They're often behind firewalls and can't participate.

2) The blog post:  I think the post author's attempt was a good, honest try and an example of what the documentation suite might become.  I agree it is hard to come up with good, tested examples across multiple platforms and that's where some paid packages have an advantage.  I think the Python community could go a little easier on non-free tools.  Trying things and seeing what works is good in many cases but there isn't the time for that in a lot of workplaces, especially those that bill services by the hour.

--- JBB