"Gerard Flanagan" <[EMAIL PROTECTED]> wrote in news:[EMAIL PROTECTED]:
> 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
-- http://mail.python.org/mailman/listinfo/python-list