Bitching about the documentation...

[Jon Perez]

rurpy at yahoo.com wrote:

> FWIW I find Python's docs to be OK at best, with some horrible
> parts, and a lot of mediochre to poor parts.

I myself have no big beef about Python's docs, but you're certainly
not the first one to complain about them.  Xah Lee rants very
heavily against the quality against Python's docs and considers
many sections of it as written in a manner more to show-off one's
knowledge of jargon rather than to explain things properly.

I don't really notice that but this could be because I'm already
quite comfortable with jargon at the level it is used in the
Python docs (or maybe I'm one of those highfalutin' chaps as well
;-D).  Seriously though, sometimes jargon is necessary in order to
put across a point concisely and accurately so its use cannot always
be considered gratuitous.

The only problem I have with Python docs is that for most of
the the standard library API documentation, the function calls
are not organized very well (i.e. I don't believe they are
alphabetized or ordered in any intutive manner).