how to write a tutorial

[Xah Lee]

adding to my previosu comment...
In the Python tutorial:
http://python.org/doc/2.3.4/tut/node11.html

the beginning two paragraphs should be deleted. Nobody gives a shit
except a few smug academicians where the author wrote it for pleasing
himself. For 99% of readers, it is incomprehensible and irrelevant.

the first paragraph of 9.1 "A Word About Terminology" is epitome of
masturbation. The entire 9.1 is not necessary.

Large part of 9.2 "Python Scopes and Name Spaces" is again
masturbatory.

--

Most texts in computing are written by authors to defend and showcase
their existence against their peers. In a tutorial, nobody cares how
the language compared to x y and z, or what technicality is it all
about, or some humorous snippet of history only funny to the author
himself.

Particularly for texts in a tutorial context, you want to write it as
simple as possible covering the most useful basic functionalities and
concepts, and self-contained. Not showcasing your knowledge of history
of languages or your linguistic lineage byways.

For example this chapter 9 on Objects, it is not difficult to write it
without making a show of lingoes. One simply write what is of Python,
without thinking about relation to xyz languages or the "computer
science" establishment and their ways of thinkings of namespaces and
scopes and dynamic and statics and inheritances ... fucking bags of
shit.

Also, in the computing industry, documentations and tutorials often
lacks examples. Especially important in tutorials. Be fewer in words,
more in examples. (for example, unix man pages are full of arcane
abstract syntax specifications and inner-working technicalities while
most don't contain a single example of usage that is much needed.)

also, this does not mean beginning to write for dummies as the highly
successful series of "xyz for Dummies" books. These are successful
because the corpus of textbook writers are all inclined and habituated
to chalk up to jargons and intellectualization on the accounts of their
own esteem and careers. Dummy books are moronic because they assumed
the general readers are morons.

PS Another illustrative case is the official Java Tutorial. Python
tutorial is to the point on the whole. The Java Tutorial is completely
asinine. Chalking up to rocket sciences every chance with unhelpful and
misleading drivel.
Xah
 xah at xahlee.org
 http://xahlee.org/PageTwo_dir/more.html