Velocity Reviews - Computer Hardware Reviews

Velocity Reviews > Newsgroups > Programming > Python > Xah's Edu Corner: Examples of Quality Technical Writing

Reply
Thread Tools

Xah's Edu Corner: Examples of Quality Technical Writing

 
 
Xah Lee
Guest
Posts: n/a
 
      12-06-2005
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 **** in the unix **** culture, with extreme ties to Perl and
Apache (both of which has extremely mother****ed docs), but can wean
itself from a **** milieu and stand pure and clean to become a paragon
of technical writing.

------------
Reminder for the purpose of this post:

The world's mother ****ers 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 **** 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...ndamentals.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 ****ing crap)

• Scheme (R5RS)
http://www.schemers.org/Documents/St...5rs-Z-H-2.html

• Scheme (Teaching yourself Scheme in Fixnum Days)
http://www.ccs.neu.edu/home/dorai/t-...eme-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/w...bni_papri.html

Xah
http://www.velocityreviews.com/forums/(E-Mail Removed)
http://xahlee.org/

 
Reply With Quote
 
 
 
 
Steve Holden
Guest
Posts: n/a
 
      12-06-2005
Xah Lee wrote:
[...]
> • No author masturbation. (if fact, you won't see a first-person
> perspective, as is the case with most quality tech writing.)
>
> We [...]


Will new readers please note that this author is well-known for posting
inflammatory and irrelevant material on many inappropriate network
newsgroups.
--
Steve Holden +44 150 684 7255 +1 800 494 3119
Holden Web LLC www.holdenweb.com
PyCon TX 2006 www.python.org/pycon/

 
Reply With Quote
 
 
 
 
Alex Stapleton
Guest
Posts: n/a
 
      12-06-2005

On 6 Dec 2005, at 04:55, Xah Lee wrote:

> i had the pleasure to read the PHP's manual today.
>
> http://www.php.net/manual/en/


To be fair, the PHP manual is pretty good most of the time. I mean,
just imagine trying to use PHP *without* the manual?! It's not like
the language is even vaguely consistent.
 
Reply With Quote
 
Pascal Bourguignon
Guest
Posts: n/a
 
      12-06-2005
"Xah Lee" <(E-Mail Removed)> writes:

> 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!


Do you have an "Approved by Xah Lee" seal logo they could put on their web page?

--
__Pascal Bourguignon__ http://www.informatimago.com/

"Remember, Information is not knowledge; Knowledge is not Wisdom;
Wisdom is not truth; Truth is not beauty; Beauty is not love;
Love is not music; Music is the best." -- Frank Zappa
 
Reply With Quote
 
Ulrich Hobelmann
Guest
Posts: n/a
 
      12-06-2005
Pascal Bourguignon wrote:
> Do you have an "Approved by Xah Lee" seal logo they could put on their web page?


Funny, that'd *exactly* mirror the opinion I have of PHP

(btw, why is this posted to every newsgroup EXCEPT a PHP one? make us
feel good?)

--
Majority, n.: That quality that distinguishes a crime from a law.
 
Reply With Quote
 
Sherm Pendley
Guest
Posts: n/a
 
      12-06-2005
Ulrich Hobelmann <(E-Mail Removed)> writes:

> btw, why is this posted to every newsgroup EXCEPT a PHP one?


Xah's a pretty well-known troll in these parts. I suppose he thinks someone
is going to take the bait and rush to "defend" the other languages or some
such nonsense.

sherm--

--
Cocoa programming in Perl: http://camelbones.sourceforge.net
Hire me! My resume: http://www.dot-app.org
 
Reply With Quote
 
Jon Perez
Guest
Posts: n/a
 
      12-07-2005
Sherm Pendley wrote:

> Xah's a pretty well-known troll in these parts. I suppose he thinks someone
> is going to take the bait and rush to "defend" the other languages or some
> such nonsense.


Actually, I think Xah often has a point, except he can't
seem to express it without resorting to profanity and
a controlled manner, thus giving the impression he's a
troll.

Also, he seems to be blissfully unaware of the concept
of netiquette.

 
Reply With Quote
 
Erik Max Francis
Guest
Posts: n/a
 
      12-07-2005
Jon Perez wrote:

> Actually, I think Xah often has a point, except he can't
> seem to express it without resorting to profanity and
> a controlled manner, thus giving the impression he's a
> troll.
>
> Also, he seems to be blissfully unaware of the concept
> of netiquette.


His "points" have about the same legitimacy as banging on the keyboard
until it breaks and then crying for an hour. At least if he did that,
we'd have to hear from him less.

--
Erik Max Francis && (E-Mail Removed) && http://www.alcyone.com/max/
San Jose, CA, USA && 37 20 N 121 53 W && AIM erikmaxfrancis
I want to know God's thought; the rest are details.
-- Albert Einstein
 
Reply With Quote
 
Gerald Klix
Guest
Posts: n/a
 
      12-07-2005
That's the most accurate description of Xah's behaviour I've read so far.

Jon Perez schrieb:
> Sherm Pendley wrote:
>
>
>>Xah's a pretty well-known troll in these parts. I suppose he thinks someone
>>is going to take the bait and rush to "defend" the other languages or some
>>such nonsense.

>
>
> Actually, I think Xah often has a point, except he can't
> seem to express it without resorting to profanity and
> a controlled manner, thus giving the impression he's a
> troll.
>
> Also, he seems to be blissfully unaware of the concept
> of netiquette.
>

 
Reply With Quote
 
Xah Lee
Guest
Posts: n/a
 
      12-08-2005
Post-modernism, Academia, and the Tech Geeking ****heads

• the Sokal Affair
http://en.wikipedia.org/wiki/Sokal_Affair

• SCIGen and World Multi-Conference on Systemics, Cybernetics and
Informatics *
http://pdos.csail.mit.edu/scigen/

• What are OOP's Jargons and Complexities, Xah Lee
http://xahlee.org/Periodic_dosage_dir/t2/oop.html

• Politics and the English Language, George Orwell
http://xahlee.org/p/george_orwell_english.html

Xah
(E-Mail Removed)
http://xahlee.org/

 
Reply With Quote
 
 
 
Reply

Thread Tools

Posting Rules
You may not post new threads
You may not post replies
You may not post attachments
You may not edit your posts

BB code is On
Smilies are On
[IMG] code is On
HTML code is Off
Trackbacks are On
Pingbacks are On
Refbacks are Off


Similar Threads
Thread Thread Starter Forum Replies Last Post
COVER LETTERS RESUME EXAMPLES AND CV EXAMPLES AVAILABLE rawebadvert3 Computer Support 0 05-25-2007 04:18 AM
Xah's Edu Corner: Examples of Quality Technical Writing Xah Lee Perl Misc 79 03-09-2006 09:06 AM
Xah's Edu Corner: Examples of Quality Technical Writing Xah Lee Java 80 02-16-2006 08:36 AM
bogus messages from register@syr.edu and administrator@syr.edu ndbergej Computer Support 3 06-05-2005 11:22 PM
A technical question from a non-technical person. Any suggestions appreciated. Graham Cross VOIP 2 01-27-2005 09:13 PM



Advertisments