how to write a tutorial

[John Hunter]

>>>>> "Xah" == Xah Lee <xah at xahlee.org> writes:

    Xah> at places often a whole paragraph on some so called computer
    Xah> science jargons should be deleted. They are there more to
    Xah> showcase inane technicality than do help the
    Xah> reader. (related, many passages with jargons should be
    Xah> rewritten sans inane jargon. e.g. mutable object.)

The concept of mutable objects is extremely important in python, and
understanding is the key to answering two recurring newbie questions

  * Why can't lists or dictionaries be keys to dictionaries?

  * Why does using a list as a default value for a keyword argument in
    a function definition often lead to unexpected results?

So it is definitely appropriate material in a tutorial.  

As for jargon, it is hard to argue that "object" is inane jargon in
python.  In fact, the base class for new-styled classes is indeed
"object", and if you want to write one of these classes yourself, you
need to do 'class MyClass(object)'.  So object is not inane jargon in
an object oriented programming language.  You still with me?

OK, now on to mutable.  mutable means changeable, albeit it's a little
more of an obscure word than changeable, but it does roll off the
tongue a bit more easily.  Perhaps 'changeable object' would be more
accessible to some readers, but it doesn't flow as well.  So the
python tutorial should perhaps define mutable when it introduces it.
Which it does somewhat implicitly; the first time mutable is mentioned in the
docs, in the context of strings

  Unlike strings, which are immutable, it is possible to change
  individual elements of a list:


And now for my last musing on a new topic "How to write a critique":
It is much more constructive to suggest new text for documentation
than to brand it inane.

JDH