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