Python doc problem example: gzip module (reprise)

[Mike Meyer]

"Andrea Gavana" <andrea_gavana at tin.it> writes:
> 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.

The thing is, the library documentation that Xah Lee is complaining
about is a *reference document*. It says so right in the title:
"Python Library Reference". As such, it makes lousy tutorial
documentation. Xah correctly points this out, which is akin to
pointing out that the sky is not green.

Now, if he wanted to call the PSF to task for not providing sufficient
tutorial documentation, he might have a point. On the other hand, the
PSF has limited resources, and:

> OTOH, usually by using some simple google-fu, it is easy to find a sample
> application for a particular method.

The Python Cookbook should show up a lot in this search. If other
people are providing tutorial documentation, then it's not at clear
that the PSF should be duplicating that effort. If they had infinite
resources, it's clear they should be providng the documentation Xah
Lee wants. It doesn't, so letting third parties provide tutorial
documentation is probably the best use of the limited resources that
they have available.

And, since we're talking about Mr. Lee, let's add the obligatory
request that you help google find him by description by adding this
link to your page: <a href="http://xahlee.org/">stupider than spam</a>

     <mike
-- 
Mike Meyer <mwm at mired.org>			http://www.mired.org/home/mwm/
Independent WWW/Perforce/FreeBSD/Unix consultant, email for more information.