I've been using python for a good few months.
And im really bothered by some aspects of the documentation.
I think that there should be a clear effort to provide API style information, rather than the mixed state that things currently are.
There are tools for C++/Java...that are part of the official distributions that provide API style docs.
Here's what gets me: when u look up something in pydoc, you have no idea what it returns/expects in terms of types. Now, since python is not an explicitely typed language, I ask rhetorically, how can u have good docs that tell u the return/input types without making the language explicitely typed?
Make the documenation system explictely typed.
The clarification needs to happen somewhere along the lines, and I really think that the world would rather not have it happening at runtime.
This could clear up a lot of confusion and further python's effectiveness.
-Hunter.