Queue module and Python Documentation Rant

[Roel Schroeven]

Roger Binns wrote:
> Pretty much anyone who has done PHP in anger raves about their docs (me
> included).  Not only is the meta-data really good (eg which version the
> item was introduced in etc), but the user contributions are what makes
> the big difference.  Also as far as I can tell, every single page includes
> an example.

Well, not everybody: I don't like the PHP documentation at all. Part of 
the problem is precisely the user comments: they are unstructured by 
their very nature, and you always have to read them all because it's 
very much possible to miss important information on special cases etc. 
if you don't. And often they contradict each other, or are written by 
newbies who feel it is their duty to share their clumsy re-invention of 
the wheel to the whole community.

What should be done is regularly incorporate the useful information from 
the user comments in the documentation itself and then remove the user 
comments. That way the useful information is collected in one place, 
while it is now scattered over the documentation proper on one side and 
the different user comments on the other side.

I also find it very confusing and impractical that the user comments are 
sorted from newest to oldest: very often new comments are reactions to 
old comments. That requires me to scroll down-up-down-up-down-up, very 
frustrating. It's like top-posters on Usenet.

Actually, I like the Python documentation much better. IMO it is both 
more comprehensive and does a better job of explaining the underlying 
concepts. For instance, I had absolutely no trouble finding the 
documentation of the Queue module and understanding its purpose and usage.

-- 
"Codito ergo sum"
Roel Schroeven