how to write a tutorial

[alex23]

Re: how to write a tutorial

Daniel Bickett wrote:[color=blue]
> Chris Mattern wrote:[color=green]
> > alex23 wrote:
> >[color=darkred]
> > > Having read your comments on women,[/color]
> >
> > I hadn't looked at that part of his site until now. I can only[/color][/color]
say:[color=blue][color=green]
> > gah. Haven't seen something like that since Dave Sim's infamous
> > "Tangent" essay.[/color]
>
> It's painfully obvious that it is all for the sole purpose of[/color]
negative[color=blue]
> attention.
> You guys are just begging for a YHBT ;-)
>
> Daniel Bickett[/color]

[alex23]

Re: how to write a tutorial


Daniel Bickett wrote:[color=blue]
> You guys are just begging for a YHBT ;-)[/color]

Point taken :) I've noticed very few people even acknowledge his posts
at all; I'll follow the group lead and do the same.

Cheers!

- alex23

[Jonathan Burd]

Re: how to write a tutorial

Xah Lee wrote:[color=blue]
> adding to my previosu comment...[/color]

<snip>

*plonk*

--
"Women should come with documentation." - Dave

[Christos TZOTZIOY Georgiou]

Re: how to write a tutorial

On Sun, 23 Jan 2005 12:28:12 -0500, rumours say that Hans Nowak
<hans@zephyrfal con.org> might have written:
[color=blue]
>Xah Lee wrote:[color=green]
>> 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.[/color]
>
>So I can just take a copy of the tutorial to the bathroom next time.
>Thanks for the tip, man![/color]

The first day I (got) laid my eyes on the Python tutorial, I knew the
days of "Pyboy", "Pythouse" and "Python 10" were over. I'm glad that
finally others, too, really grok the "joy of Python programming".

PS I just *love* the Classes chapter centerfold. All-time classic.
--
TZOTZIOY, I speak England very best.
"Be strict when sending and tolerant when receiving." (from RFC1958)
I really should keep that in mind when talking with people, actually...

[Xah Lee]

Re: how to write a tutorial

in my previous two messages, i've criticized the inanity of vast
majority of language documentations and tutorials in the industry. I've
used the Python tutorial's chapter on class as an example. I've
indicated that proper tutorial should be simple, covering just common
cases, be self-contained, and be example based. Documenting or covering
the language's functionalities manifest as it is. An exemplary case of
this style i've indicated is Stephen Wolfram Mathematica documentation.

Following is a tutorial on Python's classes. It is part of a
a-Python-a-day mailing list. As an example, it shows what i mean by
covering the language's functionalities as is, without needing to chalk
up to rocket sciences. If expanded slightly and edited, it can supplant
sections 9.0 to 9.4 of the Python tutorial. Languages Tutorials should
follow this style.

---------------
From: xah@xahlee.org
Subject: [perl-python] 20050124 classes and objects
Date: January 24, 2005 6:44:14 AM PST
To: perl-python@yahoogro ups.com

# -*- coding: utf-8 -*-
# Python

# in Python, one can define a boxed set
# of data and functions, which are
# traditionally known as "class".

# in the following, we define a set of data
# and functions as a class, and name it xxx
©class xxx:
© "a class extempore! (^_^)"
© i=1 # i'm a piece of data
© def okaydokey(self) : return "okaydokey"
© def square(self,a): return a**a

# in the following,
# we create an object, of the class xxx.
# also known as "instantiat e a class".
x = xxx()

# data or functions defined in a class
# are called the class's attributes or
# methods.
# to use them, append a dot and
# their name after the object's name.
print 'value of attribute i is:', x.i
print "3 squared is:", x.square(3)
print "okaydokey called:", x.okaydokey()

# in the definition of function inside a
# class, the first parameter "self" is
# necessary. (you'll know why when you need to)

# the first line in the class definition
# is the class's documentation. It can
# be accessed thru the __doc__
# attribute.
print "xxx's doc string is:", x.__doc__

# one can change data inside the class
x.i = 400

# one can also add new data to the class
x.j=4
print x.j

# or even override a method
x.square = 333
# (the following line will no longer work)
# print "3 squared is:", x.square(3)

# in Python, one must be careful not to
# overwrite data or methods defined in a
# class.

#-----------------------

# for a obfuscated treatment with a few
# extra info, see
# http://python.org/doc/2.3.4/tut/node11.html

# in Python terminal, type help() then
# topic CLASSES to read about existing
# datatypes as classes, and classes in
# Python

# try to write a class with one data of
# integer and two functions, one
# increases it by 1, one decreases it by
# 1. note: inside a class definition,
# to refer to data inside itself use
# self. e.g. self.i
Xah
xah@xahlee.org

http://xahlee.org/PageTwo_dir/more.html

[Keith Thompson]

Re: how to write a tutorial

"Xah Lee" <xah@xahlee.org > writes:
[snip][color=blue]
> Following is a tutorial on Python's classes.[/color]
[snip]

Please stop posting this to comp.lang.c. I'm sure the folks in most
of the other newsgroup aren't interested either -- or if they are,
they can find it in comp.lang.pytho n.

Followups redirected.

--
Keith Thompson (The_Other_Keit h) kst-u@mib.org <http://www.ghoti.net/~kst>
San Diego Supercomputer Center <*> <http://users.sdsc.edu/~kst>
We must do something. This is something. Therefore, we must do this.

[Charlton Wilbur]

Re: how to write a tutorial

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

XL> I've used the Python tutorial's chapter on class as
XL> an example. I've indicated that proper tutorial should be
XL> simple, covering just common cases, be self-contained, and be
XL> example based.

"Correct" is not in your list of criteria. Big surprise, that.

Followups set appropriately.

Charlton


--
cwilbur at chromatico dot net
cwilbur at mac dot com

[Terry Reedy]

Re: how to write a tutorial

Xah the arrogant wrote, among other things,

# one can change data inside the class
x.i = 400

# one can also add new data to the class
x.j=4
print x.j

# or even override a method
x.square = 333
# (the following line will no longer work)
# print "3 squared is:", x.square(3)

# in Python, one must be careful not to
# overwrite data or methods defined in a
# class.
--------------

However, there are several errors in the above that would mislead a Python
learner. I advise any such to ignore Xah's writings.

Terry J. Reedy

[Brian van den Broek]

Re: how to write a tutorial

Terry Reedy said unto the world upon 2005-01-26 14:08:[color=blue]
> Xah the arrogant wrote, among other things,[/color]

<SNIP>
[color=blue]
> However, there are several errors in the above that would mislead a Python
> learner. I advise any such to ignore Xah's writings.
>
> Terry J. Reedy[/color]

Hi all,

here's a thought:

There isn't any doubt that these 'tutorials' are generally unwelcome
and unhelpful. Numerous people have kindly taken the time to flag some
of the problems. So much so that any competent google of the archives
would quickly reveal the group consensus on their instructional merit.

I submit that continued corrections and advice of this sort are
counter-productive. I understand the good intentions behind the
corrections. (Indeed, my own level of Python-fu is such that it is
possible that I might have been mislead the 'tutorials' without these
corrections; I thus appreciate the correctors' efforts.) But, such
corrections are troll-food and make it unlikely that the 'game' of
posting such tutorials will soon loose its magical power to amuse the
OP. They all but ensure that there will be more such 'tutorials' to
correct.

Could we try to ignore them in the hopes that without the light of
attention they will wither, meanwhile trusting the many extant reviews
and google to do their work?

(In case it isn't obvious: none of this is intended as a criticism of
Terry or any of the others who have been 'fighting the good fight'; I
just think a change of strategy might be in order.)

Best to all

Brian vdB

[Jeremy Jones]

when self-absorbed narcissists discover usenet [ was: how to writea tutorial ]

Brian van den Broek wrote:
[color=blue]
> Terry Reedy said unto the world upon 2005-01-26 14:08:
>[color=green]
>> Xah the arrogant wrote, among other things,[/color]
>
>
> <SNIP>
>[color=green]
>> However, there are several errors in the above that would mislead a
>> Python learner. I advise any such to ignore Xah's writings.
>>
>> Terry J. Reedy[/color]
>
>
> Hi all,
>
> here's a thought:
>
> There isn't any doubt that these 'tutorials' are generally unwelcome
> and unhelpful. Numerous people have kindly taken the time to flag some
> of the problems. So much so that any competent google of the archives
> would quickly reveal the group consensus on their instructional merit.
>
> I submit that continued corrections and advice of this sort are
> counter-productive. I understand the good intentions behind the
> corrections. (Indeed, my own level of Python-fu is such that it is
> possible that I might have been mislead the 'tutorials' without these
> corrections; I thus appreciate the correctors' efforts.) But, such
> corrections are troll-food and make it unlikely that the 'game' of
> posting such tutorials will soon loose its magical power to amuse the
> OP. They all but ensure that there will be more such 'tutorials' to
> correct.[/color]

<snip>

I couldn't agree with you more. *However*, when the person posting is
self-absorbed to the extent that he doesn't realize that others exist
and don't give a crap about their wishes or discomforts, it puts you in
a "damned if you do, damned if you don't" situation. I honestly think
that we're stuck with the inane ramblings of Xah Lee regardless of
whether we feed his trolling or ignore him. But I do think that
responding to him in order to preach some sense into him is futile. He
is right about everything and can't be swayed by the likes of us mere
mortals. So, ignore him, post responses for the benefit of others out
there, entertain yourself by pointing out to yourself and others his
folly, but don't waste your time replying back to him and trying to talk
sense. Like I said, we're stuck with him.


Jeremy

[Terry Reedy]

Responding to trollish postings.

[New subject line]

In response to my response to a trollish posting...
[color=blue]
> There isn't any doubt that these 'tutorials' are generally unwelcome and
> unhelpful. Numerous people have kindly taken the time to flag some of the
> problems. So much so that any competent google of the archives would
> quickly reveal the group consensus on their instructional merit.[/color]

Yes, having advised many people to use Google, I thought it appropriate to
flag one particular section that I thought dangerous.
[color=blue]
> I submit that continued corrections and advice of this sort are
> counter-productive.[/color]

I agree that 'correcting' Xah's writing is useless, and so I refrained. If
asked 'What's wrong with the part you flagged?', I would stick with my
original advice: "Ignore it".
[color=blue]
> Could we try to ignore them in the hopes that without the light of
> attention they will wither, meanwhile trusting the many extant reviews
> and google to do their work?[/color]

I only read that particular post because it lacked the [Perl-Python] flag
and because I was interested in the subject. Sure, now that I have added
my one and presumably only review, let's everyone stop ;-)
[color=blue]
> (In case it isn't obvious: none of this is intended as a criticism of
> Terry or any of the others who have been 'fighting the good fight'; I
> just think a change of strategy might be in order.)[/color]

No offense taken. My personal strategy is to read only as much of trollish
threads as I find interesting or somehow instructive, almost never respond,
and then ignore the rest. I also mostly ignore discussions about such
threads.

Terry J. Reedy

[John Machin]

Re: Responding to trollish postings.


Terry Reedy wrote:[color=blue]
>
> No offense taken. My personal strategy is to read only as much of[/color]
trollish[color=blue]
> threads as I find interesting or somehow instructive, almost never[/color]
respond,[color=blue]
> and then ignore the rest. I also mostly ignore discussions about[/color]
such[color=blue]
> threads.
>[/color]

Indeed. Let's just nominate XL to the "Full Canvas Jacket" website
(http://www.ratbags.com/ranters/) and move on.

[Peter Hansen]

Re: Responding to trollish postings.

John Machin wrote:[color=blue]
> Indeed. Let's just nominate XL to the "Full Canvas Jacket" website
> (http://www.ratbags.com/ranters/) and move on.[/color]

I'm not sure how reliable that site could be. After
all, it contains no articles with the words "autocoding ",
"threeseas" , or "rue" (other than as the French "street").

Sad, really. ;-)

(Neither has it been updated in the last two years. :-( )

-Peter

[Craig Ringer]

Re: how to write a tutorial

On Wed, 2005-01-26 at 09:35 +0000, Keith Thompson wrote:[color=blue]
> "Xah Lee" <xah@xahlee.org > writes:
> [snip][color=green]
> > Following is a tutorial on Python's classes.[/color]
> [snip]
>
> Please stop posting this to comp.lang.c. I'm sure the folks in most
> of the other newsgroup aren't interested either -- or if they are,
> they can find it in comp.lang.pytho n.[/color]

Going by the general reaction on c.l.py, I think it'd be more accurate
if you left that at "Please stop posting".

Sorry for the cross-post, and for this "perl-python" moron who appears
to have nothing to do with either, or any knowledge of them.

--
Craig Ringer

[axel@white-eagle.co.uk]

Re: how to write a tutorial

In comp.lang.perl. misc Xah Lee <xah@xahlee.org > wrote:[color=blue]
> Following is a tutorial on Python's classes. It is part of a
> a-Python-a-day mailing list. As an example, it shows what i mean by
> covering the language's functionalities as is, without needing to chalk
> up to rocket sciences. If expanded slightly and edited, it can supplant
> sections 9.0 to 9.4 of the Python tutorial. Languages Tutorials should
> follow this style.[/color]

It is crap, not a tutorial, but just an aide-memoire for someone who
presumably knows the stuff anyway.

And keep it where it belongs please.

Axel