Examples of Quality Documentation

Xah Lee, 200512

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

------------
http://xahlee.org/perl-python/quality_docs.html
☄