how to write a tutorial
jdhunter at ace.bsd.uchicago.edu
Fri Jan 21 15:53:48 CET 2005
>>>>> "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.
More information about the Python-list