Xah Lee wrote: > i had the pleasure to read the PHP's manual today. > > http://www.php.net/manual/en/ > > although Pretty Home Page is another criminal hack of the unix lineage, > but if we are here to judge the quality of its documentation, it is a > impeccability. > > it has or possesses properties of: > > · To the point and useful. > > PHP has its roots in mundaness, like Perl and Apache. Its doc being > practicality oriented isn't a surprise, as are the docs of Perl and > Apache. > > · Extreme clarity! > > The doc is extremely well-written. The authors's writing skills > shows, that they can present their ideas clearly, and also that they > have put thoughts into what they wanted to say. > > · Ample usage examples. > > As with Perl's doc, PHP doc is not afraid to show example snippets, > yet not abuse it as if simply slapping on examples in lieu of proper > spec or discussion. > > · Appropriate functions or keywords are interlinked. > > This aspect is also well done in other quality docs, such as > Mathematica, Java, MS JScript, Perl's official docs. > > · No abuse of jargons. > > In fact, it's so well written that there's almost no jargons in its > docs, yet conveys its intentions to a tee. This aspect can also be seen > in Mathematica's doc, or Microsoft's JScript doc, for examples. > > · No author masturbation. (if fact, you won't see a first-person > perspective, as is the case with most quality tech writing.) > > We must truely appreciate the authors of the PHP doc. Because, PHP, as > a free shit in the unix shit culture, with extreme ties to Perl and > Apache (both of which has extremely motherfucked docs), but can wean > itself from a shit milieu and stand pure and clean to become a paragon > of technical writing. >
--- original Sat Dec 31 11:44:54 2005 +++ corrected Sat Dec 31 11:56:59 2005 @@ -1,28 +1,28 @@ -i had the pleasure to read the PHP's manual today. +I had the pleasure to read the PHP's manual today. http://www.php.net/manual/en/ -although Pretty Home Page is another criminal hack of the unix lineage, -but if we are here to judge the quality of its documentation, it is a +Although Pretty Home Page is another criminal hack of the unix lineage, +if we are here to judge the quality of its documentation, it is an impeccability. -it has or possesses properties of: +It has or possesses properties of: - To the point and useful. PHP has its roots in mundaness, like Perl and Apache. Its doc being -practicality oriented isn't a surprise, as are the docs of Perl and +practicality-oriented isn't a surprise; so are the docs of Perl and Apache. - Extreme clarity! The doc is extremely well-written. The authors's writing skills -shows, that they can present their ideas clearly, and also that they -have put thoughts into what they wanted to say. +show, they can present their ideas clearly, and they +have put thought into what they wanted to say. - Ample usage examples. - As with Perl's doc, PHP doc is not afraid to show example snippets, + As with Perl's doc, PHP's doc is not afraid to show example snippets, yet not abuse it as if simply slapping on examples in lieu of proper spec or discussion. @@ -31,18 +31,18 @@ This aspect is also well done in other quality docs, such as Mathematica, Java, MS JScript, Perl's official docs. -- No abuse of jargons. +- No abuse of jargon. - In fact, it's so well written that there's almost no jargons in its -docs, yet conveys its intentions to a tee. This aspect can also be seen + In fact, it's so well written that there's almost no jargon in its +docs, yet it conveys its intentions to a tee. This aspect can also be seen in Mathematica's doc, or Microsoft's JScript doc, for examples. -- No author masturbation. (if fact, you won't see a first-person +- No author masturbation. (In fact, you won't see a first-person perspective, as is the case with most quality tech writing.) -We must truely appreciate the authors of the PHP doc. Because, PHP, as +We must truly appreciate the authors of the PHP doc. Because PHP, as a free shit in the unix shit culture, with extreme ties to Perl and -Apache (both of which has extremely motherfucked docs), but can wean +Apache (both of which have extremely motherfucked docs), can wean itself from a shit milieu and stand pure and clean to become a paragon of technical writing. HTH -- Brad -- http://mail.python.org/mailman/listinfo/python-list
