As I was reading this discussion on the drawbacks of Python, I was greatly surprised to see that a few answers, including the currently top-rated one, mentioned Python's documentation as one of its weak sides.
I have always considered Python's documentation to be excellent. I also know that a lot of effort is being invested in keeping Python's documentation correct, useful and up-to-date. A sizable part of my own work as a Python core developer so far was focused on documentation.
To make this post constructive, I propose the following:
If you find some flaw in Python's documentation, don't just sit there fuming. The Python developers really care about documentation, and will gladly work towards making it better. You have a few options to influence:
- Open a documentation issue on the Python issue tracker.
- Send an email to the firstname.lastname@example.org mailing list.
- Or just shout it out loud (in a blog, a forum, Stack Overflow, or wherever), hoping someone will pick it up.
You can also send me an email - I'll be happy to discuss and re-route the report to the appropriate destination.
P.S. While in my Python work I focus on CPython - the official C implementation, documentation is one of those areas that can benefit all implementations of Python, since they all basically implement the same "language spec" (barring some slight differences such as the ones documented here). The CPython documentation serves as the formal description of the language and its standard library. So helping make the docs better will not only help CPython, but Jython, IronPython and PyPy as well.