Xah's Edu Corner: Examples of Quality Technical Writing

X

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 **** 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
(e-mail address removed)
∑ http://xahlee.org/
 
P

Pascal Bourguignon

Xah Lee said:
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
 
U

Ulrich Hobelmann

Pascal said:
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?)
 
S

Sherm Pendley

Ulrich Hobelmann said:
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--
 
X

Xah Lee

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
(e-mail address removed)
∑ http://xahlee.org/
 
B

bradb

I don't know about anyone else, but you'd impress me much more if you
didn't swear in your posts. I am personally not offended, but it does
lower your credibility in my eyes. Just a tip.

Brad
 
X

Xah Lee

recently i got a project that involves the use of php. In 2 days, i
read almost the entirety of the php doc. Finding it a breeze because it
is roughly based on Perl, of which i have mastery.

i felt a sensation of neatness, as if php = Perl Improved, for a
dedicated job of server-side scripting. Everything is so-built-in, and
the integrated functions for web application programing such as
CGI/Database is so convenient. What a PRACTICALITY! It has gotten a
long way, even now with a independent interpreter and engine (Zend) for
embedded computation of any other mark-up lang. And, its array/hash is
kinda linguistically cleaner, by combining the two into one. (after
all, array indexes are unique, so they are denotationally and
mathematically list of keyed pairs (hashes) too) As for nested
structure, it does away with Perl's ${x}->{'whatnot'}[$x]->[$y{'z'}]
insanity. And I'm most impressed by its extremely well-written
documentation.

But as i know the lang more, my feeling changed, yet “Perl
Improved†is still apt, with a new interpretation.

see
http://tnx.nl/php

If Unix, Apache, Perl, MySQL etc shit can impact the world with
motherfucking evolutionary outrageous $free$ lies, why should we fault
Pretty Home Page?

Xah
(e-mail address removed)
∑ http://xahlee.org/
 
R

Roedy Green

recently i got a project that involves the use of php. In 2 days, i
read almost the entirety of the php doc. Finding it a breeze because it
is roughly based on Perl, of which i have mastery.

that's very lovely, but off topic. Trolling for language flame wars
belong is comp.lang.java.advocacy.
 
T

Thomas G. Marshall

Roedy Green said something like:
that's very lovely, but off topic. Trolling for language flame wars
belong is comp.lang.java.advocacy.

I had plonked him back in May for this kind of crap. I suggest you do the
same.
 
I

IchBin

Thomas said:
Roedy Green said something like:

I had plonked him back in May for this kind of crap. I suggest you do the
same.

It's better just to ignore him because he is only looking for the
attention and pseudo respect..

"You don't put a fire out with gasoline".

--


Thanks in Advance...
IchBin, Pocono Lake, Pa, USA
http://weconsultants.servebeer.com/JHackerAppManager
__________________________________________________________________________

'If there is one, Knowledge is the "Fountain of Youth"'
-William E. Taylor, Regular Guy (1952-)
 
T

Tin Gherdanarra

Xah said:
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
(e-mail address removed)
∑ http://xahlee.org/

I agree with everything you say. You should check
out the following links. They will amuse and
enlight you.

Post-modernism, Schizo-Islamism and the world at large:
http://www.rhfweb.com/mctom.html

S.N.A.F.U., D.I.S.C.O. and C.R.I.S.I.S. reaching crisis
proportions:
http://koti.welho.com/mjack1/

The Dalai Llama is just another EVIL spitting mammal:
http://pages.123-reg.co.uk/sumon-262452/

It's a pussy-eat-pussy world. Tech Geek fuckheads might beg
to disagree, however:
http://www.johnnydisco.com/

Secularism, homosexuality, fringe humor finally dominating
occidental tech elite. End neigh, doctors say:
http://www.qgeeks.org

Don't mention it, at your service
Tin
 
T

Tin Gherdanarra

Xah said:
recently i got a project that involves the use of php. In 2 days, i
read almost the entirety of the php doc. Finding it a breeze because it
is roughly based on Perl, of which i have mastery.

I suspect that you are a computer program posing as a human
usenet correspondent.

Please answer these questions:

If Alice goes to the supermarket to buy a pint of
milk, does her head go with her? Please elaborate.

What is the difference between my disher blowing
a fuse and your boss blowing a fuse? Please elaborate.

How can you turn off the light of a candle? Why does
it work?
 
M

Martin Christensen

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1


Tin> I suspect that you are a computer program posing as a human
Tin> usenet correspondent.

Tin> Please answer these questions: [...]

Will you accept a solution in Perl? He has mastery of that language,
you know. You might have better luck if you phrase your questions in
Perl, too, since he doesn't seem to understand it when people tell him
to bugger off in plain English.

Say, there's a thought...

Martin
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.1 (GNU/Linux)
Comment: Using Mailcrypt+GnuPG <http://www.gnupg.org>

iEYEARECAAYFAkOg0CUACgkQYu1fMmOQldVP9ACfSzQBq7S1QX0jA2/nA2JaC+BB
4ZoAoMOn5Qe9oJHGtINWKNBQsz879R6r
=bp6G
-----END PGP SIGNATURE-----
 
J

javuchi

Why do you have such a need of being hating everything and everybody
and expressing it so offen?
Can you live without hate?
Can you let others live without your hates?
 
L

Luc The Perverse

javuchi said:
Why do you have such a need of being hating everything and everybody
and expressing it so offen?
Can you live without hate?
Can you let others live without your hates?

A person can live without hate, living love and working towards bettering
humanity.

But as for people in general - I'm not so sure. I'm not sure my opinion on
hate - since I value people's opinions and diversity, hate seems unbecoming,
but then so does computer gaming ;)

Westernization sweeps accross all countries though, and it is no longer
vogue to be so self centered. This will help with the most overt types of
hatred.
 
J

John Bokma

Martin Christensen said:
Perl, too, since he doesn't seem to understand it when people tell him
to bugger off in plain English.

"It" buggers off if everybody ignores it. "It" posts because it knows that
its actions pisses off so many people.
 
?

=?iso-8859-1?q?M=E5ns_Rullg=E5rd?=

Martin Christensen said:
Tin> I suspect that you are a computer program posing as a human
Tin> usenet correspondent.

Tin> Please answer these questions: [...]

Will you accept a solution in Perl? He has mastery of that language,
you know. You might have better luck if you phrase your questions in
Perl, too, since he doesn't seem to understand it when people tell him
to bugger off in plain English.

OK, lets try:

die;
 
K

Keith Thompson

javuchi said:
Why do you have such a need of being hating everything and everybody
and expressing it so offen?
Can you live without hate?
Can you let others live without your hates?

Xah Lee is a well-known troll. Replying to him is a waste of time.
Please just ignore him. (A killfile is an effective way to do so.)
 
X

Xah Lee

Responsible Software Licensing

Xah Lee, 200307

Software is a interesting invention. Software has this interesting
property, that it can be duplicated without cost, as if like copying
money. Never in history are goods duplicable without cost. But with the
invention of computer, the ephemeral non-physical programs break that
precept. In digital form, programs and music and books all become goods
in essentially infinite quantity.

All is good except, bads in digital form can also multiply equally,
just as goods. Well known examples are computer viruses and email
spams. Unknown to the throng of unix morons are software bads. In a
unix moron's mind, the predominant quip among hackers is “where is
your code?â€, singnifying the mentality that a hacker's prestige is
judged on how much code he has contributed to the community. Therefore,
every fucking studs and happy-go-lucky morons put their homework on the
net, with a big stamp of FREE, and quite proud of their
“contributions†to the world. These digital bads, including
irresponsible programs, protocols, and languages, spread like viruses
until they obtained the touting right of being the STANDARD or MOST
POPULAR in industry, as if indicating superior quality. Examplary are
C, Perl, RFC, X-Windows, Apache, MySQL, Pretty Home Page (and almost
anything out of unix). The harm of a virus is temporal. The harm of
irresponsible software (especially with unscrupulous promotion) is the
creation of a entire generation of bad thinking and monkey coders. The
scale can be compared as to putting a bullet in a person brain, versus
creating a creed with the Holocaust aftermath.

Distribution of software is easily like pollution. I thought of a law
that would ban the distribution of software bads, or like charging for
garbage collection in modern societies. The problem is the difficulty
of deciding what is good and what is bad. Like in so many things, i
think the ultimate help is for people to be aware; so-called education;
I believe, if people are made aware of the situation i spoke of, then
irresponsible software will decrease, regardless any individual's
opinion.

The most important measure to counter the tremendous harm that
irresponsible software has done to the industry is to begin with
responsible licenses, such that the producer of a software will be
liable for damage incurred thru their software. As we know, today's
software license comes with a disclaimer that essentially says the
software is sold as is and the producer is not responsible for any
damage, nor guaranteeing the functionality of the software. It is this,
that ferments all sorts of sloppitudes and fads and myths to rampage
and survive in the software industry. Once when software producers are
liable for their products, just as bridge or airplane or transportation
or house builders are responsible for the things they build, then
injurious fads and creeds the likes of (Perl, Programing Patterns,
eXtreme Programing, “Universal†Modeling Language...) will
automatically disappear by dint of market force without anyone's
stipulation.

In our already established infrastructure of software and industry
practices that is so already fucked up by existing shams, we can not
immediately expect a about-face in software licenses from 0 liability
to 100% liability. We should gradually make them responsible. And this,
comes not from artificial force, but gradual establishment of awareness
among software professionals and their consumers. (Producers include
single individual to software houses, and consumers include not just
mom & pop but from IT corps to military.)

Please spread this idea.
--------------------------------
This post is archived at
http://xahlee.org/UnixResource_dir/writ/responsible_license.html

Xah
(e-mail address removed)
∑ http://xahlee.org/
 

Ask a Question

Want to reply to this thread or ask your own question?

You'll need to choose a username for the site, which only take a couple of moments. After that, you can post your question and our members will help you out.

Ask a Question

Members online

Forum statistics

Threads
473,757
Messages
2,569,543
Members
45,026
Latest member
camilin05

Latest Threads

Top