Queue module and Python Documentation Rant

[Bart Nessux]

Paramjit Oberoi wrote:
>>The documentation is fine.  It is pretty standard for docs constructed
>>"cathedral" style.  I do wish it was more bazaar style like the PHP
>>ones, but I don't have the time or inclination to help put the infrastructure
>>in place.  Do you?
> 
> 
> I personally really like Python documentation, and very rarely have any
> trouble with it.  However, I think it could be improved by having a
> consistent policy regarding examples.  Some modules do have examples, but
> many don't.
> 
> I think a policy that requires all modules to have examples, and a
> consistent place for them in the documentation, would be a big help. 

I agree. It'd be nice to see examples based on how one intends to use 
the language. For example, demonstrate  how one might use a module in a 
sequential manner for basic sys-admin scripting purposes, then show how 
the same module might be used procedurally with functions to do 
something larger and more complex, and finally give an example of the 
most complex scenario (object oriented) in which someone like Param 
might want to use a module. IMO, this would cover all the bases.

Python appeals to such a vast user base. Why not make the docs useful to 
everyone regardless of their knowledge of programming concepts?

Also, the docs aren't that bad. I was just frustrated. Once I cooled 
down and read harder, I figured it out.