Bitching about the documentation...

[rurpy at yahoo.com]

<gene.tani at gmail.com> wrote:
> rurpy at yahoo.com wrote:
> > skip at pobox.com wrote:
--snip--
> > > 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.

And so it is with me too.  But it often takes me much longer than it
should to find what I need.  And everytime I (or you) don't find it in
Python's docs, that is evidence of the lack of quality of Python's
docs.

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

For perl and C, yes, that's (close to) what I'm telling you.  Perl I
learned
exclusively from the man pages, before WWW.  I used it for 10 years
before I ever bought a printed book.   C I learned exclusively from the

K&R book.  I tried to learn Python from the "official" docs but found
it
impossible.  I bought Beasley's book (I think this may have predated
Martelli's book but I don't remember) which I thought quite good and
which I still turn to before the Python docs in most cases.

> So either spend a little money, buy the Nutshell and Cookbook, (or,

If one is required to buy a book to use free software, it is not
really free, is it?

> 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

Books are no different than anything else.  There are a few good ones,
a lot of average ones, and a few bad ones.  (Actually, the distribution
is probably skewed to the bad side because it is easier to write a bad
book than a good one).  Also most of these books seem to be tutorial
in nature.  That's not what I want.  I want a clear, lucid, *concise*,
compete, accurate, description of Python (i.e. what Python's docs
should be.)  Given that Beazley (and I presume Martelli) did that, and
the reference manuals of other languages did that, I don't see why
Python can't do that (other than the fact that writing documentation
is not fun for most people, and hard to do well.)

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

I did.  I thought they both were poor.

> 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

That's a very good list and I will save a copy, thanks.  But what
does it have to do with Python's documentation?

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

Are you under the impression that an assortment of pages
out on the internet constitutes (or substitutes for) the "official"
documentation that comes with python?