Xah Lee, 2005-12
I had the pleasure to read the PHP's manual today.
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 skill 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 documentation media's utility aspect is also almost always employeed 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 jargon 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. (in fact, it is not written using a first-person perspective, as is the case with most professional documentation.)
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 are the worst cases of tech writing), but can wean itself from a shit milieu and stand pure and clean to be a paragon of technical writing.
The world's worst docs are the Unix (man pages)
http://www.FreeBSD.org/cgi/man.cgi,
Perl http://perldoc.perl.org/,
Apache http://httpd.apache.org/docs/1.3/,
Python http://www.python.org/doc/2.4.2/
.
As i have alluded or expounded before, the unix & Apache are criminally the worst, Perl being a immediate follow up. Python's on a class of its own, being a mutated Computer Sciency pretension whose usability is worse than Perl's.
Here is 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 manual
http://www.gnu.org/software/emacs/manual/
and elisp manual
http://www.gnu.org/software/emacs/elisp-manual/elisp.html
ale both of high quality.)
• Java's 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 “Learning the Java Language” http://java.sun.com/docs/books/tutorial/java/index.html is a documentation garbage. (due, in this case, not for lack of writing skill, but lack of understanding OOP and pedagogy.))
• Scheme's official doc (R5RS)
http://www.schemers.org/Documents/Standards/R5RS/HTML/r5rs-Z-H-2.html
• Scheme tutorial (Teaching yourself Scheme in Fixnum Days, by Dorai Sitaram)
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 tutorial. If you want to see clarity with verbosity, see Emacs Lisp Intro, Emacs manual, Elisp manual. 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 essays:
Page created: 2005-12. © 2005 by Xah Lee.