Bitching about the documentation...
gene.tani at gmail.com
Tue Dec 6 03:01:47 CET 2005
rurpy at yahoo.com wrote:
> 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
> 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
> too. There are plenty of people on this list willing to sing python's
> for balance, there should be people willing to openly point out
> 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
> 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
> > 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