Python doc problem example: gzip module (reprise)

[Rick Wotnaz]

"Gerard Flanagan" <grflanagan at yahoo.co.uk> wrote in
news:1131192936.228280.150530 at g44g2000cwa.googlegroups.com: 

> Xah Lee wrote:
>> Python Doc Problem Example: gzip
>>
[...]
>> A quality documentation should be clear, succinct, precise.
>> And, the least it assumes reader's expertise to obtain these
>> qualities, the better it is.
>>
>> Vast majority of programers using this module really just want
>> to compress or decompress a file. They do not need to know any
>> more details about the technicalities of this module nor about
>> the Gzip compression specification. Here's what Python
>> documentation writers should do to improve it:
>>
>> • Rewrite the intro paragraph. Example: “This module prov
> ides a
>> simple interface to compress and decompress files using the GNU
>> compression format gzip. For detailed working with gzip format,
>> use the zlib module.”. The “zlib module” phrase should be
>  linked to its
>> documentation.
>>
>> • Near the top of the documentation, add a example of usage.
>> A example is worth a thousand words:
>>
>>  # decompressing a file
>> import gzip
>> fileObj = gzip.GzipFile("/Users/joe/war_and_peace.txt.gz",
>> 'rb'); fileContent = fileObj.read()
>> fileObj.close()
>>
>>  # compressing a file
>> import gzip
>> fileObj = gzip.GzipFile("/Users/mary/hamlet.txt.gz", 'wb');
>> fileObj.write(fileContent)
>> fileObj.close()
>>
> 
> """
> You want to create the world before which you can kneel: this is
> your ultimate hope and intoxication.
> 
> Also sprach Zarathustra.
 
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. Some of us learn by example; sometimes an example is 
all we need to use a particular feature (especially one that we 
don't often have need for). The criticism that the documentation 
would be improved by adding some model code is valid for *all* 
documentation, I think, not just Python's.

Typically, when someone proposes changes to documentation to an 
open source project, someone else will come along and remind 
everyone that it's all volunteer effort, so why shouldn't the one 
doing the propopsing be the one to make the change? In the case of 
documentation, that approach would mean that those who have the 
least idea of how a module works should be the ones to describe it 
for everyone else, which seems a little backward to me. The 
examples should come from those who know what they're doing and 
they should explain what the example is doing -- just the sort of 
things a casual user wants to learn quickly.

Someone is sure to jump in now and point to sample code, which 
nearly all reasonably major packages include. That's good stuff. 
With (for example) wxPython, it's the only useful documentation, or 
rather, it's the only thing that makes the wxWidgets documentation 
useful. Links to code samples in the documentation would be fine in 
lieu of snippets of example calls. But there's not enough of either 
in most documentation.

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.

-- 
rzed