# [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
