Survey: improving the Python std lib docs

[rzed]

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

One thing I would love to see in any function or class docs is a few example invocations, preferably non-trivial. If I need to see more, I can read the entire doc, but most times I just want a refresher on how the function is called. Does it use keywords? Are there required nameless parameters? In what order? A line or two would immediately clarify that most of the time. 

Apart from that, links to docs for uncommon functions (or to the docs of the module, if there are many) would be at least somewhat useful.