Bitching about the documentation...

gene tani gene.tani at
Tue Dec 6 03:01:47 CET 2005

rurpy at wrote:
> skip at 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 (" 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:
> >
> >
> 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.

Well, the docs are what they are, I can find what I need.  Are you
telling us you learned C#, smalltalk, lisp, C, perl, whatever, from 1
website only, without looking at any books, without spending any money
on IDEs or any software?  Cause that's what you're asking here.

So either spend a little money, buy the Nutshell and Cookbook, (or,
look at dozens of books, and many excellent ones:

or spend some time, look at the 2 complete intro books published on the

web, there's also:

Here's some FAQ/gotchas:

So i don't think you ca really say the lang spec, the VM and the dev
environment in general are poorly documented.

More information about the Python-list mailing list