Python doc problem example: gzip module (reprise)

[Mike Meyer]

Paul Rubin <http://phr.cx@NOSPAM.invalid> writes:
> Mike Meyer <mwm at mired.org> writes:
>> 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.
> I'm not sure which particular library Xah Lee was complaining about
> but lots of the lib docs are awful even as references.

That's true, but Xah Lee's proposed fixes do nothing to address this
problem.

>> 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. 
> It seems to me that since the PSF is so persnickety about code
> licenses (and that is a good thing), it should be persnickety about
> documentation licenses too.  Lots of FSF documentation projects were
> undertaken because while there were good docs in existence for
> whatever it was, there were none that the FSF could include in its
> distros.  It's similarly not so great if Python users have to rely on
> proprietary docs.  Of course the PSF has to prioritize its tasks and
> some things will necessarily stay far down on the "list" for quite a
> while, but they should at least BE on the list.

To my knowledge the PSF isn't doing anything about including the
documentation with their distribution, so they shouldn't care about
the licenses. Wanting to bundle a good tutorial for everything in the
library might be on the list, but the licenses on third-party
tutorials shouldn't matter until you are considering bundling them. In
that light, the only major omission I can think of is Tkinter, as the
only good docs - tutorial, reference, or otherwise - is the Grayson's
book.

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