Examples of Quality Documentation in Computing Industry

By Xah Lee. Date:

PHP Documentation

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 explanation.

• 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.

Worst Documentations

The world's worst docs are:

As i have alluded or expounded before, the unix and 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.

Examples of Quality Documentation

Here is a sample list of a variety of quality technical writings:

• Mathematica documentation. http://reference.wolfram.com/mathematica/guide/Mathematica.html

• Microsoft's JScript official docs. http://msdn.microsoft.com/en-us/library/hbxc2t98.aspx

• Emacs's documentations:

• 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.