Survey: improving the Python std lib docs

[Ned Batchelder]

On Friday, May 12, 2017 at 6:02:58 AM UTC-4, 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.
> 

I have a number of ideas for improving the docs, but I think there is a
larger issue that needs to be addressed first: there is no BDFL for the
docs. They are written and maintained piecemeal, by the core dev that
wrote the code. If one documentation-focused person had decision-making
power over all the docs, then we might be able to get some consistency
throughout.

As it is, if I make a suggestion about the itertools docs (why do we need
20-line "equivalent to" Python code, and why don't we have any usage
examples?), then I have to debate it with the developer of itertools,
who has a different aesthetic and style than the developer of logging,
or email, or re, and so on.

If we had one person who had the authority to make doc-wide decisions,
then we might be able to move towards coherent guidelines for the docs
to be more uniform.

--Ned.