"Christopher J. Bottaro" <[EMAIL PROTECTED]> wrote in message news:[EMAIL PROTECTED] > 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 -- http://mail.python.org/mailman/listinfo/python-list
