Bitching about the documentation...

[skip at pobox.com]

    >> Gee, I wonder if I typed "sort" into the search box on the wiki it
    >> might turn up something useful?  Well, what do you know?
    >> 
    >> 2 results of about 4571 pages. (0.19 seconds)
    >> 
    >> 1. HowTo/Sorting
    >> 2. SortingListsOfDictionaries

    rurpy> Are we talking about the same Search box (at the top right of the
    rurpy> wiki page, and labeled "search"?  Well, yes I did enter "sort"
    rurpy> and got (as I said) a long list of archived maillist postings.

Probably.  There are two search buttons, Title and Text.  Always try the
Title search first, as it only searches page titles.  If that is unhelpful,
then try the Text search.  That searches the bodies of the pages.  I
generally never use that search, preferring instead to use Google's
"site:wiki.python.org ..." restricted search which is going to apply their
page rank algorithms to the hits (and be faster to boot).  I don't know how
hard it would be to modify the wiki's Text button so it executes the
appropriate Google search.  Probably not too hard.  I'll look.

    rurpy> Well, I'm not totally sure but I think I would be willing to a
    rurpy> least try contributing something.  A large amount of the time I
    rurpy> waste when writing Python programs is directly attributable to
    rurpy> poor documentation.  (To be fair Python is not the only software
    rurpy> with this problem.)

    rurpy> But, the standard responce of "don't complain, fix it yourself"
    rurpy> is bogus too.  There are plenty of people on this list willing to
    rurpy> sing python's praises, for balance, there should be people
    rurpy> willing to openly point out python's flaws.  Documentation is
    rurpy> certainly one of them.  And I was correcting a posting that
    rurpy> explicitly said there was exceptionaly good information in that
    rurpy> Howto.  That was just plain wrong.

Sure, feel free to point of flaws.  Just don't let that be the only way you
contribute.  Over time the value of your criticism (valid or not) will be
discounted.

The preferred way to correct problems with the documentation is to submit a
bug report to SourceForge.  Many of the active developers (including those
who do write most of documentation) don't necessarily track c.l.py closely,
so postings here often will get lost because people can't attend to them
immediately.

The problem with marching in here and saying "fix the docs" is that you are
an unknown quantity (I certainly don't recognize your email address and as
far as I've seen you never sign your posts.  I don't believe I've ever seen
contributions from you either.  (Can't double-check right now because
SourceForget is basically unresponsive.)  The combination makes you look
suspiciously like a troll.  I doubt that's the case.  Troll detectors are
notorious for generating false positives.  Still, my threat assessment level
got raised.

Operating under the rurpy's-not-a-troll assumption, your posts suggest to me
that you don't understand how Python is developed.  Behind the scenes lots
of documentation *does* get written.  In my experience it hass generally not
been written by people who whine, "fix the docs".  In short, there seems to
be no shortage of people willing to castigate the Python developers for
poor documentation.  There does appear to be a shortage of people willing to
actually roll up their sleeves and help.

The other thing to remember is that most of the people who wind up writing
the documentation don't personally need most of the documentation they
write.  After all, they are generally the authors of code itself and are
thus the experts in its use.  It's tough to put yourself in the shoes of a
novice, so it's tough to write documentation that would be helpful for new
users.  It's extremely helpful if new users submit documentation patches as
they figure things out.  It's generally unnecessary to write large tomes.
Often all that's needed is a few sentences or an example or two.

Skip