Xah's Edu Corner: Examples of Quality Technical Writing

[Xah Lee]

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
 xah at xahlee.org
 ∑ http://xahlee.org/