Python Documentation Blows!

[Michael]

># It is a shame that the only limitation of a great is documentation.
>
>Maybe I'm misunderstanding, but if you are implying that good docs
>make a great language, you're mistaken.  After all, you're advocating
>Java in a python forum.  I do agree that java has good documentation,
>but I not think Java should be considered "great" in any capacity.  If
>the python docs are so bad, you should be specific about how and why.
>Python is great for countless other reasons which are unrelated to
>documentation.  I think the python docs are exceptional.
>  
>
IMO, PHP has the best documentation of basic language functionality. 
That certainly doesn't mean I think it is the best language. I think 
Python's library reference documentation is very good but the 
documentation of the basic language itself is sometimes lacking or 
confussing or just hard to find. Especially given that Python is 
somewhat unique in many ways and has certain gotchas that tend to 
confuse experienced programmers that are new to Python. Also it seems 
that certain popular 3rd party modules should be more closely documented 
with the library reference. Twisted would be a good example. Also it'd 
be nice to see a collection of short example programs that make use of 
various functionality and libraries available from Python.

I'd say that good docs don't make a great language but bad docs can ruin 
a great language. Python's docs aren't bad but they could be a lot better.

wxPython would be my example of some of the worst (non-existant) 
documentation available for Python while PyGame would be my example of 
some of the best.