Steve D'Aprano <steve+pyt...@pearwood.info> writes: > 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? > > (They're not my ideas, the originated on Reddit.) > > > (1) Table of functions/classes at the start of each module doc > > The docs for builtins starts with a table of built-in functions: > > https://docs.python.org/3/library/functions.html
>From my point of view, a good (manually maintained) documentation should not contain information that can easily be obtained automatically. Ideally, we should separate between overview information (explaining the essential concepts and their relations) and detail information (list of classes, functions, ...) with links between them. The detail information is likely generated automatically from the source. > ... > (2) The PHP documentation allows you to search for a term by typing it into > the URL after the domain, e.g. to search for "split", go to: > > http://php.net/split > > > If you try the same thing with the Python docs: > > http://python.org/split > > you get a 404. Suggestion: 404s should redirect and search the docs. Generate an "index" page from the complete documentation with links to the term definitions. Then people who miss such a functionality can bookmark that page. -- https://mail.python.org/mailman/listinfo/python-list
