I just posted a lengthy message to comp.lang.python/python-list about
Python's docs; the title is "Documentation suggestions". A short
summary of the post is: "The RefGuide is hard to read and hard to keep
updated. Do we need a friendly language description? If we do that,
should the existing RefGuide be abandoned or maintained?" See the
post for the full argument.