how to write a tutorial

[Xah Lee]

i've started to read python tutorial recently.
http://python.org/doc/2.3.4/tut/tut.html

Here are some quick critique:

quick example:
If the input string is too long, they don't truncate it, but return it
unchanged; this will mess up your column lay-out but that's usually
better than the alternative, which would be lying about a value. (If
you really want truncation you can always add a slice operation, as in
"x.ljust( n)[:n]".

better:
If the input string is too long, they don't truncate it, but return it
unchanged;
-----------------
delete: Reverse quotes (``) are equivalent to repr(), but their use is
discouraged.
-----------------
similarly, many places mentioning uncritical info such as warning or
reference to other languages should be deleted.

the tutorial should be simple, concise, to the point, stand along.
Perhaps 1/5th length of the tutorial should be deleted for better.
Follow the above principles.

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

one easy way to understand these principles is to compare perl's
documentation or unix man pages to Python's. The formers are often
irrelevant, rambling on, not stand-along (it is written such that it
unnecessarily requires the reader to be knowledgable of lots of other
things). Python docs are much better, but like many computer language
manuals, also suffers from verbiage of tech jargons. (these jargons or
passages about them are usually there to please the authors
themselves).

A exemplary writing in this direction is the Mathematica manual by
Stephen Wolfram. Any intelligent layman sans computer science degree
can read it straightforward ly, and learn unhindered a language that is
tantamount to features of lisp languages. Such documentation is not
difficult to write at all. (contrary to the lot of "computer
scientists" or IT pundits morons.) All it take is some simple
principles outlined above.
Xah
xa*@xahlee.org
http://xahlee.org/PageTwo_dir/more.html

[Diez B. Roggisch]

Xah Lee wrote:

i've started to read python tutorial recently.
http://python.org/doc/2.3.4/tut/tut.html
Finally! It was about time...
Here are some quick critique:

Given that you seem to be totally inert to critique yourself - e.g. your
continued posting of useless language comparison, and the plethorea of
posts requesting to stop that and limit yourself to your mailing list - I
doubt you'll get much attention for that.

--
Regards,

Diez B. Roggisch

[drewc]

You should not be giving such advice! (and the crosspost ... WTF?).

I've been trying to follow along with your perl/python yahoo group, but
your posts are terrible.

Perhaps you should provide the output of the code you post. Then i'd
actually know what i'm trying to achieve. As it is i have to cut/paste
your code into an interpreter just to figure out what it does.

What does this have to do with Lisp? (i'm in c.l.l).

drewc

Xah Lee wrote:

i've started to read python tutorial recently.
http://python.org/doc/2.3.4/tut/tut.html

Here are some quick critique:

quick example:
If the input string is too long, they don't truncate it, but return it
unchanged; this will mess up your column lay-out but that's usually
better than the alternative, which would be lying about a value. (If
you really want truncation you can always add a slice operation, as in
"x.ljust( n)[:n]".

better:
If the input string is too long, they don't truncate it, but return it
unchanged;
-----------------
delete: Reverse quotes (``) are equivalent to repr(), but their use is
discouraged.
-----------------
similarly, many places mentioning uncritical info such as warning or
reference to other languages should be deleted.

the tutorial should be simple, concise, to the point, stand along.
Perhaps 1/5th length of the tutorial should be deleted for better.
Follow the above principles.

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

one easy way to understand these principles is to compare perl's
documentation or unix man pages to Python's. The formers are often
irrelevant, rambling on, not stand-along (it is written such that it
unnecessarily requires the reader to be knowledgable of lots of other
things). Python docs are much better, but like many computer language
manuals, also suffers from verbiage of tech jargons. (these jargons or
passages about them are usually there to please the authors
themselves).

A exemplary writing in this direction is the Mathematica manual by
Stephen Wolfram. Any intelligent layman sans computer science degree
can read it straightforward ly, and learn unhindered a language that is
tantamount to features of lisp languages. Such documentation is not
difficult to write at all. (contrary to the lot of "computer
scientists" or IT pundits morons.) All it take is some simple
principles outlined above.
Xah
xa*@xahlee.org
http://xahlee.org/PageTwo_dir/more.html

[John Hunter]

>>>>> "Xah" == Xah Lee <xa*@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

[Frank Buss]

drewc <dr***@rift.com > wrote:

What does this have to do with Lisp? (i'm in c.l.l).

he is a troll, but one who confess this fact:

http://www.xahlee.org/Netiquette_dir/troll.html

--
Frank Buß, [e-mail]
http://www.frank-buss.de, http://www.it4-systems.de

[CBFalconer]

Xah Lee wrote:

i've started to read python tutorial recently.
http://python.org/doc/2.3.4/tut/tut.html

Here are some quick critique:

This has absolutely nothing to do with c.l.c, nor most of the
cross-posted groups. F'ups set. Why did you do such a foul
cross-posting in the first place.

--
"If you want to post a followup via groups.google.c om, don't use
the broken "Reply" link at the bottom of the article. Click on
"show options" at the top of the article, then click on the
"Reply" at the bottom of the article headers." - Keith Thompson

[M Jared Finder]

Xah Lee wrote:

i've started to read python tutorial recently.
http://python.org/doc/2.3.4/tut/tut.html

What does this have to do with Perl, Lisp, Scheme, or C?

-- MJF

[Jeremy Bowers]

On Fri, 21 Jan 2005 03:08:50 -0800, Xah Lee wrote:

i've started to read python tutorial recently.
http://python.org/doc/2.3.4/tut/tut.html

Here are some quick critique:

You don't have the respect points for anyone to give a damn. Step one
would be demonstrating that you understand the language enough to have a
valid opinion, which we're all still waiting on.

[Jeffrey Cunningham]

On Fri, 21 Jan 2005 03:08:50 -0800, Xah Lee wrote:

i've started to read python tutorial recently.
http://python.org/doc/2.3.4/tut/tut.html
(snip rest of misleading filler)
http://xahlee.org/PageTwo_dir/more.html

The first line is solipsistic (..like..'so what?'). But I think its all
misleading. The real purpose of his cross-post is to get people to visit
his website, ooh-and-ahh at his unique and daring Bush-bashing at the top,
and finally admire (along with Xah himself) the pictures he takes of
himself.

Vanity, vanity, all is vanity...

The only remaining question is 'why does he restrict his cross-posting to
this particular collection of groups?' I don't have an answer to that one.

[incidentally, I'm still cracking up over k.t. and the soldier...]
--Jeff

[Lucas Raab]

Daniel Bickett wrote:

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.

<snip>

Um, maybe that was his point...