Python-URL! - weekly Python news and links (Nov 17)

[rurpy at yahoo.com]

On Nov 17, 11:10 am, "Francesco Guerrieri" <f.guerri... at gmail.com>
wrote:
> On Mon, Nov 17, 2008 at 6:44 PM,  <rurpy at yahoo.com> wrote:
>> On Nov 17, 8:54 am, "Gabriel Genellina" <python-... at phaseit.net>
>> wrote:
>>>     Candidate to *Longest and Most Boring Thread of the Year* - started
>>>     more than a month ago, currently discussing "The official definition
>>>     of call-by-value", and "What't the value of an object":
>>>         http://groups.google.com/group/comp.lang.python/t/6163956596a8c082/
>>
>> Nice.  The Python Reference defines objects, the core concept
>> of Python, as id, type, and value, and then leaves one clueless
>> about what a value is, and several notable Python contributors
>> declare the subject boring.
>>
>> I guess this goes a long way to explaining why the Python docs
>> suck so badly in many areas.
>
> This is a commonly heard assertion.
> Maybe it's just me but I find that on average Python documentation on
> the web is pretty good (*) and does its job very well.

"Good" is a subjective word.  And actually I too
think they are pretty good, at least relative to
the quality of many free software projects.  But
Python is a very high quality language (albeit
with a few quirks) and the quality of the docs
really doesn't rise to the quality of the language.

The discussion here and in part of the longest
most boring thread was caused by the lack of a
decent description of Python objects.  The 2.6
docs say coverage of new-style classes is still
incomplete although it appears better than in 2.5.

Besides missing information much text appears to
have been written by people in a contest to see
who could describe something in the fewest possible
words and still defend it as arguably correct.
One really needs to keep the end goal in mind --
transmittal of the information to the reader.

The organization is still bizarre, with the
*builtin* types and functions documented in the
Library(!) manual rather that Language Manual
where one would expect them (in that I hardly
think you could have a Python language implementation
without a int type or a list type.)  One would
think the Library Manual would describe the
modules that were not-essential to the core
Python.

And then there are lots of little things like
the comment in the description of the packages
in import statement: "XXX: Can't be bothered to
spell this out right now", with a url to a
description of packages in Python 1.5.  (From
the Python 2.5 docs, haven't installed 2.6 yet.)
How would you feel if you bought a book and read
that in it?

But to see the difference between the Python Docs
and "good" documentation, take a look at something
like David Beasley's "Essential Python".  It is
not perfect either of course (among other things
it copies nearly verbatim the incomplete Python
Doc definition of "object") and it is not intended
to define the language, but the organization and
clarity of writing is way better than the Python
Docs.

When you look at the the details of the individual
modules, there is a nearly infinite list of minor
to moderate problems.

All that being said, the docs are slowly getting
better over time, and the people working on them
certainly deserve thanks and appreciation for the
hard work that has gone into them.

> One is also left to wonder why all these critics don't take some
> initiative and work to improve it.

What makes you think that all of them don't?