Python doc problem example: gzip module (reprise)

[Andrea Gavana]

Hello NG,

> I've managed to avoid reading Xah Lee's diatribes for the most
> part. Since you included the *WHOLE THING* in your post, I had an
> "opportunity" to see what he had to say, and for once I agree with
> some of it.

<snip>

> I would love to see examples for essentially every function and
> method. And not just something that echoes the signature, but some
> context to show how it might be useful. That would be in the
> "intoxication" class of ultimate hopes. In most cases, though, it
> would be *extremely* helpful for a casual user of that part of the
> package.

I tend to agree with you, Rick. I usually don't like Xah's "posting
behavior", but  this time he has done, in my opinion, a "constructive"
criticism (and he didn't even say *fuck* once in the whole post!!!). I am
quite a newbie in Python, I usually deal with wxPython that is sometimes not
very "pythonic", or not enough "pythonic". As a newbie (in whatever language
you wish), I would like to open the docs about a particular library, class
or method and find a small "sample application" of it. I think many newbies
learn by examples. I don't mean to say anything negative about the docs or
the docs' authors, but I would imagine that having a simple example of use
for all the methods in a class/library would be a nice and valuable
improvement for the docs.
OTOH, usually by using some simple google-fu, it is easy to find a sample
application for a particular method. This is due mainly to the popularity of
Python, and its popularity is due to its beauty as a language. Compared to
other I learnt in the past, like C++, Fortran and Matlab, I have about 99%
less jitters now that I use Python ;-) .

Andrea.

"Imagination Is The Only Weapon In The War Against Reality."
http://xoomer.virgilio.it/infinity77