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. At http://www.ccs.neu.edu/home/dorai/t-y-scheme/t-y-scheme-Z-H-1.html , accessed on 2012-09-27 ]

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.

Python Documentation Sucks

  1. Python Doc Problem: os.system
  2. Python Doc Problem: os.path.split()
  3. Python Doc Problem: sort()
  4. Python Doc Problem: gzip
  5. Python Documentation Problems
  6. Python Documentation Author Masturbation
  7. How to Improve Python Doc; Notes on Rewriting Python Regex Doc
  8. Why Python's Documentation Sucks
  9. Python Poetry: the __main__ Stanza
  10. perldoc Coming of Age, What Python Can Learn From?
  11. Examples of Quality Documentation in Computing Industry
  12. Python Doc Links Dead
  13. Python Doc Links All Dead
  14. Python = Pretentious Sheet
  15. Optional Function Parameters in Computer Language Docs (the idiocy thereof)

If you have a question, put $5 at patreon and message me.