how to write a tutorial

Daniel Bickett dbickett at gmail.com
Sun Jan 23 16:57:25 CET 2005


> Most texts in computing are written by authors to defend and showcase
> their existence against their peers.

When you aren't busy `showcasing' your ignorance, this is *all* i see
in everything you write.

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

You couldn't be farther from the truth. To preface a document by
illustrating it's similarities to other languages is to better prepare
a reader who may have experience in those languages. As for the
snippet of history, few people desire to live life as cynical as you
do, and one would hope even fewer take their own opinion and assume it
applies to their peers, as you have just done.

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

You of all people are the least qualified to say this, as you are the
most guilty of such a crime.

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

Then please be so kind as to give us all a pleasant surprise, and take
the place of the productive reformer rather than the angsty
criticizer. Your vision as to the errors in the tutorial is *clearly*
less clouded than ours, so only *you* are in the position to write the
proper replacement.

Daniel Bickett



More information about the Python-list mailing list