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. ------------ Reminder for the purpose of this post: The world's mother fuckers are the community and doc writers of: Unix (man pages), Perl, Apache, Python. As i have alluded or expounded before, the unix & Apache are criminally the worst, Perl being a close follow up. Python's on a class of its own, being a mutated Computer Sciency fuck that is possibly even worse on the whole than Perl's doc. Here a sample list of a variety of quality technical writings: • Mathematica http://documents.wolfram.com/mathematica/ • Microsoft's JScript official docs http://msdn.microsoft.com/library/en-us/script56/html/js56jsconjscriptfundamentals.asp • Emacs Lisp Introduction (by Robert J. Chassell) http://www.gnu.org/software/emacs/emacs-lisp-intro/ (GNU project's documentations are almost always quality documentations. For example, the official emacs and elisp docs ale both of high quality.) • Java official doc http://java.sun.com/j2se/1.4.2/docs/api/index.html Java, being a bottled-up inflexible language with incessant lies backup by huge amounts of $money$, nevertheless hired professional writers for its huge official documentation — produced a very well done doc for a very complex language. (however, the official Java Tutorial is a fucking crap) • Scheme (R5RS) http://www.schemers.org/Documents/Standards/R5RS/HTML/r5rs-Z-H-2.html • Scheme (Teaching yourself Scheme in Fixnum Days) http://www.ccs.neu.edu/home/dorai/t-y-scheme/t-y-scheme-Z-H-1.html These are all quality technical writings. They have different styles and audiences and coverages. If you want to see clarity and concision, see JScript, PHP, and Scheme intro. If you want to see clarity with verbosity, see Emacs Lisp Intro. For clarity sans arcana yet covers esoterica, see the Mathematica doc. Some of these are written for people with no experience in programing, yet functions as equivalent to teaching/documenting extremely advanced programing concepts. If you want to see proper use of jargons at a IT professional level, see the Java doc. If you want to see exemplary tech writing in a academic style, see the Scheme R5RS. Related essay: Why OpenSource Documentation is of Low Quality http://xahlee.org/UnixResource_dir/writ/gubni_papri.html Xah [EMAIL PROTECTED] ∑ http://xahlee.org/ -- http://mail.python.org/mailman/listinfo/python-list
