473,547 Members | 2,553 Online
Bytes | Software Development & Data Engineering Community
+ Post

Home Posts Topics Members FAQ

Xah's Edu Corner: Examples of Quality Technical Writing

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...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 fucking 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
xa*@xahlee.org
http://xahlee.org/

Dec 6 '05 #1
102 6966
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/

Dec 6 '05 #2

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.
Dec 6 '05 #3
"Xah Lee" <xa*@xahlee.org > 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
Dec 6 '05 #4
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 :D

(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.
Dec 6 '05 #5
Ulrich Hobelmann <u.*********@we b.de> 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
Dec 6 '05 #6
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. ;-)

Dec 7 '05 #7
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 && ma*@alcyone.com && 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
Dec 7 '05 #8
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. ;-)

Dec 7 '05 #9
Post-modernism, Academia, and the Tech Geeking fuckheads

• 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
xa*@xahlee.org
http://xahlee.org/

Dec 8 '05 #10

This thread has been closed and replies have been disabled. Please start a new discussion.

Similar topics

9
1595
by: Xah Lee | last post by:
Dear Joe, It is well known that you are an avid hater of Microsoft, from their technologies to their leader to their business practices. I have now and then seen your impassioned expression of this hatred, scattered among your newsgroup posts. Personally, i have an inherent distrust toward big organizations. This applies to Microsoft....
385
16979
by: Xah Lee | last post by:
Jargons of Info Tech industry (A Love of Jargons) Xah Lee, 2002 Feb People in the computing field like to spur the use of spurious jargons. The less educated they are, the more they like extraneous jargons, such as in the Unix & Perl community. Unlike mathematicians, where in mathematics there are no fewer jargons but each and every...
14
1875
by: Xah Lee | last post by:
sometimes in the last few months, apparently Microsoft made changes to their JavaScript documentation website: http://msdn.microsoft.com/library/default.asp?url=/library/en-us/script56/html/1e9b3876-3d38-4fd8-8596-1bbfe2330aa9.asp so that, one has to goddamn press the "expand" button to view the documentation, for every goddamn page. ...
28
2435
by: Xah Lee | last post by:
Sometimes you want your text to flow into multiple columns, as in newspaper's layout. However, as of 2005-12 this is not yet possible. One can make-do by hard-coding it into HTML TABLE using multiple columns. It is a pain because when you change your text, you have to manually cut and paste to justify each and every columns by trial-n-error....
23
3597
by: Xah Lee | last post by:
The Concepts and Confusions of Pre-fix, In-fix, Post-fix and Fully Functional Notations Xah Lee, 2006-03-15 Let me summarize: The LISP notation, is a functional notation, and is not a so-called pre-fix notation or algebraic notation. Algebraic notations have the concept of operators, meaning, symbols placed around arguments. In...
62
3858
by: Xah Lee | last post by:
Criticism versus Constructive Criticism Xah Lee, 2003-01 A lot intelligent people are rather confused about criticism, especially in our “free-speech” free-for-all internet age. When they say “constructive criticisms are welcome” they mostly mean “bitching and complaints not welcome”. Rarely do people actually mean that...
12
3572
by: Xah Lee | last post by:
Of Interest: Introduction to 3D Graphics Programing http://xahlee.org/3d/index.html Currently, this introduction introduces you to the graphics format of Mathematica, and two Java Applet utilities that allows you to view them with live rotation in a web browser. Also, it includes a introductory tutorial to POV-Ray.
0
7703
Oralloy
by: Oralloy | last post by:
Hello folks, I am unable to find appropriate documentation on the type promotion of bit-fields when using the generalised comparison operator "<=>". The problem is that using the GNU compilers, it seems that the internal comparison operator "<=>" tries to promote arguments from unsigned to signed. This is as boiled down as I can make it. ...
0
7947
jinu1996
by: jinu1996 | last post by:
In today's digital age, having a compelling online presence is paramount for businesses aiming to thrive in a competitive landscape. At the heart of this digital strategy lies an intricately woven tapestry of website design and digital marketing. It's not merely about having a website; it's about crafting an immersive digital experience that...
0
7797
tracyyun
by: tracyyun | last post by:
Dear forum friends, With the development of smart home technology, a variety of wireless communication protocols have appeared on the market, such as Zigbee, Z-Wave, Wi-Fi, Bluetooth, etc. Each protocol has its own unique characteristics and advantages, but as a user who is planning to build a smart home system, I am a bit confused by the...
0
6032
agi2029
by: agi2029 | last post by:
Let's talk about the concept of autonomous AI software engineers and no-code agents. These AIs are designed to manage the entire lifecycle of a software development projectplanning, coding, testing, and deploymentwithout human intervention. Imagine an AI that can take a project description, break it down, write the code, debug it, and then...
1
5362
isladogs
by: isladogs | last post by:
The next Access Europe User Group meeting will be on Wednesday 1 May 2024 starting at 18:00 UK time (6PM UTC+1) and finishing by 19:30 (7.30PM). In this session, we are pleased to welcome a new presenter, Adolph Dupr who will be discussing some powerful techniques for using class modules. He will explain when you may want to use classes...
0
3493
by: TSSRALBI | last post by:
Hello I'm a network technician in training and I need your help. I am currently learning how to create and manage the different types of VPNs and I have a question about LAN-to-LAN VPNs. The last exercise I practiced was to create a LAN-to-LAN VPN between two Pfsense firewalls, by using IPSEC protocols. I succeeded, with both firewalls in...
0
3473
by: adsilva | last post by:
A Windows Forms form does not have the event Unload, like VB6. What one acts like?
1
1050
muto222
by: muto222 | last post by:
How can i add a mobile payment intergratation into php mysql website.
0
748
bsmnconsultancy
by: bsmnconsultancy | last post by:
In today's digital era, a well-designed website is crucial for businesses looking to succeed. Whether you're a small business owner or a large corporation in Toronto, having a strong online presence can significantly impact your brand's success. BSMN Consultancy, a leader in Website Development in Toronto offers valuable insights into creating...

By using Bytes.com and it's services, you agree to our Privacy Policy and Terms of Use.

To disable or enable advertisements and analytics tracking please visit the manage ads & tracking page.