469,293 Members | 1,364 Online
Bytes | Developer Community
New Post

Home Posts Topics Members FAQ

Post your question to a community of 469,293 developers. It's quick & easy.

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
102 6329
I noticed, that in just about all emacs programs on the web (elisp
code), it comes with this template text as its preamble:

;; This program is free software; you can redistribute it and/or
;; modify it under the terms of the GNU General Public License as
;; published by the Free Software Foundation; either version 2, or (at
;; your option) any later version.

;; This program is distributed in the hope that it will be useful, but
;; WITHOUT ANY WARRANTY; without even the implied warranty of
;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
;; General Public License for more details.

;; You should have received a copy of the GNU General Public License
;; along with this program; see the file COPYING. If not, write to
;; the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
;; Boston, MA 02111-1307, USA.

Concerned parties and the FSF foundation, please remove the middle
section of this template. That section is mainly for lawyers, for
programers to protect themselves in the context of modern society's law
system. Legally speaking, that section is redundant because it is in
the GNU General Public License itself. The effect of that section in a
license summary is fueling the habit and sanction of irresponsible
programing we see all around us.

In place of that section, i'd propose replacing it with the following
gist:

«This program is distributed in the hope that it will be useful. The
author(s) has responsibly produced it, and will take reasonable
responsibilities with regards to the program's intended purpose and
workability. For legal aspects of WARRANTY, please see the GNU General
Public License for more details.»

Regarding these issues, please read:

Responsible Software Licensing
http://xahlee.org/UnixResource_dir/w...e_license.html

Responsible Software Licensing & the Free Software Foundation
http://xahlee.org/UnixResource_dir/w...cense_FSF.html

Xah
xa*@xahlee.org
http://xahlee.org/

Mar 4 '06 #101
Xah Lee <xa*@xahlee.org> wrote on 4 Mar 2006 10:21:11 -0800:
I noticed, that in just about all emacs programs on the web (elisp
code), it comes with this template text as its preamble:
[ .... ]
;; This program is distributed in the hope that it will be useful, but
;; WITHOUT ANY WARRANTY; without even the implied warranty of
;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
;; General Public License for more details.
[ .... ]
Concerned parties and the FSF foundation, please remove the middle
section of this template. That section is mainly for lawyers, for
programers to protect themselves in the context of modern society's law
system. Legally speaking, that section is redundant because it is in
the GNU General Public License itself.
That section is there to draw people's attention to the lack of a
warranty, to cause them to contrast it with the "warranty" offered by
non-free software, which typically is restricted to replacing the
distribution CD if it can't be read.
The effect of that section in a license summary is fueling the habit
and sanction of irresponsible programing we see all around us.
My impression is that irresponsible programming tends to come with a
guarantee to replace the distribution CD if it can't be read.
In place of that section, i'd propose replacing it with the following
gist: ??This program is distributed in the hope that it will be useful. The
author(s) has responsibly produced it, and will take reasonable
responsibilities with regards to the program's intended purpose and
workability. For legal aspects of WARRANTY, please see the GNU General
Public License for more details.??
Nah, that's too defensive and wooly. If you get an Email from a stranger
that says "checked virus-free by ....", would you believe that? No?
Then why would you believe a programmer who feels he has to assert he has
done his work "responsibly", whatever that might mean? It's legally
dubious, and wouldn't inspire any confidence whatsoever. Responsibility
is shown by actions and results, not promises.

[ .... ]
Xah


--
Alan Mackenzie (Munich, Germany)
Email: aa**@muuc.dee; to decode, wherever there is a repeated letter
(like "aa"), remove half of them (leaving, say, "a").

Mar 9 '06 #102

Please come to my forum. Why others hate America . and invite others to join
in the conversation.
--
View this message in context: http://www.nabble.com/Xah%27s-Edu-Co....html#a3362284
Sent from the Python - python-list forum at Nabble.com.

Mar 12 '06 #103

This discussion thread is closed

Replies have been disabled for this discussion.

Similar topics

9 posts views Thread by Xah Lee | last post: by
385 posts views Thread by Xah Lee | last post: by
1 post views Thread by CARIGAR | last post: by
reply views Thread by suresh191 | last post: by
reply views Thread by harlem98 | last post: by
1 post views Thread by Geralt96 | last post: by
reply views Thread by harlem98 | last post: by
By using this site, you agree to our Privacy Policy and Terms of Use.