# [EMAIL PROTECTED] / 2005-04-13 08:07:06 +1000: > On Tue, 12 Apr 2005 13:06:36 +0200, Roman Neuhauser > <[EMAIL PROTECTED]> wrote: > > > Unfortunately, the python community seems to bathe in the > > misorganized half-documentation, see e. g. > > http://marc.theaimsgroup.com/?l=python-list&m=111303919606261&w=2 > > especially the reply that (as I read it) suggested reverse > > engineering as a viable alternative to documentation. > > As I read the reply, it was a smart-arse attempt at humour, a *PUN* on > the word "list" (mailing list versus Python list). What I would call > "introspection" (not "reverse engineering") was then suggested. > > Moreover, both of the concepts mentioned in the quoted thread > (sequence.index() and the "in" operator) are IMESHO adequately > documented. > > Do you have any examples of what you regard as "misorganized > half-documentation"? Description of classes: * What's with "Programmer's Note", is the other paragraph of the description aimed at salesmen?
* Why isn't there a link to a description of "new-style classes" (presumably to the "New-style Classes" essay since, as http://www.python.org/doc/newstyle.html says, NSC aren't integrated into the standard documentation. * Aren't class objects instances of a builtin type? What should I read into "<class __main__.foo at 0x81c050c>"? distutils: * sections 10.26 through 10.45 are completely empty * http://docs.python.org/dist/listing-packages.html: "when you say packages = ['foo'] in your setup script" couldn't be any more vague I guess. Does the statement belong in the global scope? * http://docs.python.org/dist/listing-packages.html: "Then you would put package_dir = {'': 'lib'} in your setup script.": does that statement belong in the global scope, or is it a keyword argument for setup(), which would mean that the listing at http://docs.python.org/dist/module-distutils.core.html cannot be trusted as complete? lists: this is a matter of taste, but I find the split of list description between http://docs.python.org/lib/typesseq.html and http://docs.python.org/lib/typesseq-mutable.html (without pointers from typesseq.html to typesseq-mutable.html where I would expect them, such as mentioning append()) confusing. The above applies to other mutable sequential types as well, of course. In general, various parts of the documentation often refer the reader to other parts without using html anchors, what should be concise, accurate, and complete description is a meandering essay with vague formulations (see quotes from the distutils manual above), etc. There's also this thing with easy access to individual nodes: I often miss being able to type something like http://docs.python.org/os.path.expanduser and be redirected to http://docs.python.org/lib/module-os.path.html#l2h-1731 Mebbe it's just me, but I've been trying python on and off for several years now, and it's always been precisely its documentation that has made me back out. I know I'll get to know the language quite well some time, but it'll be through scars, and I'll have many f*cks behind me. > Here's a puzzle for you: Where does this list appear? What's missing? > > "..., Mullender, Nagata, Ng, Oner, Oppelstrup, ..." Sorry, I don't have time for puzzles. -- How many Vietnam vets does it take to screw in a light bulb? You don't know, man. You don't KNOW. Cause you weren't THERE. http://bash.org/?255991 -- http://mail.python.org/mailman/listinfo/python-list