Python Documentation (vs PHP stuff)

[Terry Reedy]

"Christopher J. Bottaro" <cjbottaro at alumni.cs.utexas.edu> wrote in message 
news:d5tqi2$d8l$2 at sea.gmane.org...
> rbt wrote:
>> Because PHP is such a 'thrown together' and 'bolted-on' language. If it
>> didn't have *outstanding* documentation (which it does BTW), no one
>> could even begin to understand how they got from a little HTML language
>> to a kinda/sorta OO language.
>>
>> PHP is showing its age... thanks to its docs, it's still *extremely*
>> useful.
>
> Exactly!!  See thats what I'm saying.  I _think_ its widely accepted that
> PHP has awesome documentation.  And like rbt said, that makes it 
> extremely
> useful.  Why can't Python have documentation like that?  The language is
> awesome, it just needs documentation of the same quality.

Because of these two posts (and a few others) extolling the PHP 
documentation, I decided to take a look for myself to see what the fuss was 
about and whether I could get any ideas on how to improve Python's docs.  I 
typed "PHP manual" in my Google bar and the first link was just what I 
hoped for, the PHP site manual.

First observation: the PHP manual is a combined 'kitchen-sink' volume that 
combines material that Python separates: tutorial, language reference, 
library reference, and doc for some 3rd party packages.  Hmm, perhaps the 3 
official volumes would be better integrated if combined into one manul with 
three parts.  But the difference itself between one volume with many parts 
and many volume is not critical in itself.

Next, I picked the Array chapter in the Functions section.  It starts with 
a Unix man-style intro.  Ok, but not 'awsome'.  Next come the defined 
constants, which don't mean much out of the context of the function where 
used, so this part functions as an index of names.  Then there is a long 
alphabetical list of function name/links with a one-line description of 
each.  Gee, there seem to be a lot of different sort functions.

Finally, 80% of the chapter/page consists of a thrown-together mish-mash of 
unsorted. unedited comments and questions.  Some seem like the equivalent 
of Python cookbook entries, but others are like run-of-the mill comp.lang 
postings.  So the Python equivalent of this 'document' would include the 
Python Cookbook, the Python Wiki, and some of the c.l.p archives.

Onward to the page for sort(), which bizarrely (to me) rekeys the 'array'. 
Then there is a cross-reference to the 9 other sort pages.  Is there, I 
wonder, anyplace where all 10 sort functions are discussed together?  This 
time, 90% of the page is user junk.  Randomly clicking down, I find someone 
complaining about sort dumping his keys, just as the top entry said (but 
without the big warning box that such data destruction needs).  Sorry, PHP 
doc fans: to me, this sort of  inflated, noisey bloatware is wretched, not 
outstanding.

Conclusion 1: if PHP is anything as awful as the manual, it is not for me.

Conclusion 2: the somewhat spare style of the Python docs matches the 
somewhat spare style of the language itself.  (My goodness, only one list 
sort method!).  Since this style agrees with me, I would not want it to 
change too much.

Conclusion 3: some people would apparently be happier with the Python docs 
if they were combined into one Python Manual.  This could be done as a 
virtual anthology by writing a combined Table of Contents (with links) and 
an Introduction discussing the various 'Parts' and their 
interrelationships.  It would not have to be limited to PSF material 
either.  I might even take a stab at it if I ever feel sufficiently 
ambitious and energetic.

Terry J. Reedy