Xah's Edu Corner: Examples of Quality Technical Writing

[Brad Baxter]

Xah Lee wrote:
> 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.
>

--- original	Sat Dec 31 11:44:54 2005
+++ corrected	Sat Dec 31 11:56:59 2005
@@ -1,28 +1,28 @@
-i had the pleasure to read the PHP's manual today.
+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
+Although Pretty Home Page is another criminal hack of the unix
lineage,
+if we are here to judge the quality of its documentation, it is an
 impeccability.

-it has or possesses properties of:
+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
+practicality-oriented isn't a surprise; so 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.
+show, they can present their ideas clearly, and they
+have put thought into what they wanted to say.

 - Ample usage examples.

-  As with Perl's doc, PHP doc is not afraid to show example snippets,
+  As with Perl's doc, PHP's 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.

@@ -31,18 +31,18 @@
   This aspect is also well done in other quality docs, such as
 Mathematica, Java, MS JScript, Perl's official docs.

-- No abuse of jargons.
+- No abuse of jargon.

-  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 fact, it's so well written that there's almost no jargon in its
+docs, yet it 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
+- No author masturbation. (In 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
+We must truly 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
+Apache (both of which have extremely motherfucked docs), can wean
 itself from a shit milieu and stand pure and clean to become a paragon
 of technical writing.
 
HTH

-- 
Brad