Queue module and Python Documentation Rant

[Bart Nessux]

Roger Binns wrote:

> There is a qsize() method clearly documented.  What is wrong with
> that?

Where??? The documentation for the module named Queue says nothing at 
all about this...

http://docs.python.org/lib/module-Queue.html

> The [Python] documentation is fine.

The docs are useless. One needs a Master's in CS just to read the module 
index. In general, it's far too abstract. Many have no examples for 
actual *usage* at all. Read the section about classes in the tutorial... 
how long can you stay awake? It's so abstract and scholarly that it 
boarders on being useless.

CS is applied math. However, Python does not think of itself as being 
applied, but theoretical. This is good if you're a geek with a Ph.D, but 
not if you're the average sys-admin attempting to solve an every-day 
problem.

Python has a great syntax for beginners and advanced users alike. One 
can do sequential, procedural and OO programming with it. Also, it can 
be applied to most any problem on most any platform. However, the docs 
are an exercise in futility. They remind me of the circumlocution that I 
read about in law school... constantly talking around things instead of 
about things.

This is good if everyone is on the same high-level of knowledge, but not 
for a programming language (think applied approach to problem solving) 
that has tremendous potential and is touted as user friendly for 
non-programmers. No wonder so many people use Perl. As bad as Perl is, 
it does not have a scholarly opinion of itself and is thus approachable 
and usable.

Forgive me, I'm frustrated.

Bart