Bitching about the documentation...

[rurpy at yahoo.com]

skip at pobox.com wrote:

> 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

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

> Is it as good as Google ("site:wiki.python.org sort")?  Unlikely, but it
> works fairly well.  Granted, wikis are a different way of organizing content
> than static documentation with their nicely organized chapters, sections and
> indexes, but most of us around here are software engineer types, not tech
> writers, and since we're not paid to do any of this, we get to do anything
> we want.  Most of us choose not to write documentation in our spare time.
> Go figure.  If documentation's your thing, be my guest.  Write new
> documentation, submit patches for existing documentation, rewrite it in
> Word.  I don't care. Do whatever floats your boat.  Just don't show up and
> bitch about the documentation if you're not willing to help.

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

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

> Oh, did I mention that there's an Edit link at the top of almost every page
> on the wiki and that creating new pages is pretty simple?  (Try searching
> the wiki for "WikiCourse".)  Contributing new content to the existing more
> static documentation isn't all that hard either.

As I said, I think wiki's suck.  On almost every one I find the
information
disorganised, very spotty in coverage, extremely variable is qualilty
of writing, and often seeming like a conversation walked into in the
middle of.  I still haven't figured out how to get to the Python wiki's
howto's by navigating from the front page.  IMO wikis are best used
to collect information for later editing and inclusion into more formal
documentation.  (That's a little stronger than my actual opinion but
it's too late right now more me to express it any better.)

> If you prefer the latest documentation, bookmark this page:
>
>     http://www.python.org/dev/doc/devel/index.html

Thanks I will keep that in mind.  But the obvious risk is that it
will refer to language features and changes not in the current
version.

> That's updated every few months, more frequently as new releases approach.