Bitching about the documentation...

[gene tani]

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
> 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.

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:
http://www.amazon.com/exec/obidos/tg/browse/-/285856/ref=dp_brlad_entry/103-3311503-6360648

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

web, there's also:

http://awaretek.com/tutorials.html
http://www.vex.net/parnassus/
http://directory.google.com/Top/Computers/Programming/Languages/Python/Modules/
http://cheeseshop.python.org/
http://the.taoofmac.com/space/Python/Grimoire
http://dmoz.org/Computers/Programming/Languages/Python/Modules/

http://aspn.activestate.com/ASPN/Cookbook/Python
http://python.codezoo.com/
http://sourceforge.net/softwaremap/trove_list.php?form_cat=178&xdiscrim=178

Here's some FAQ/gotchas:
http://www.ferg.org/projects/python_gotchas.html
http://zephyrfalcon.org/labs/python_pitfalls.html
http://zephyrfalcon.org/labs/beginners_mistakes.html
http://www.python.org/doc/faq/
http://diveintopython.org/appendix/abstracts.html
http://www.onlamp.com/pub/a/python/2004/02/05/learn_python.html
http://www.norvig.com/python-iaq.html
http://www.faqts.com/knowledge_base/index.phtml/fid/245
http://amk.ca/python/writing/warts

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