Python evolution: Unease

[Paul Rubin]

Peter Hansen <peter at engcorp.com> writes:
> The key distinction is that "well-documented" is clearly
> a judgment call, a personal opinion,

No it's not.  If a program has significant modules with complicated
public API's and no documentation, it's poorly documented in an
absolute sense.  A well-documented program includes docs for all
the public API's.

> So those who claim Python is well-documented are the ones who
> should improve the documentation, but those claiming that
> the documentation is poor should feel no responsibility to
> make the improvements?

Yes, precisely so.  Like if someone says "I've written this fantastic
math package, it's fast and accurate and solves every problem
perfectly, let's start a newsgroup about how to convince our PHB's to
use it and why it's so much better than every other math package
that's ever been written", and I try the package and it says that
2+2=5 and I report that bug, I've made a constructive comment and have
no further responsibility.  I've also shown that the program doesn't
live up to its claims and people wanting to do real work with it
should watch out.  If the developers want to keep making the grand
claims, they should fix the bug.  If they want to say "this package is
technically cool but gets some answers wrong, maybe you don't want to
do anything serious with it but it's fun to play with", that's
different.  But there's a constant current in clpy of "Python is great
for everything, our PHB's should all embrace it, it supports protocols
X, Y, and Z and is great for that kind of application" when those
protocols turn out to be only half-implemented, or "it's
well-documented" when the manual turns out to be only half-complete.
And the responses I see sound almost like "2+2=5 is an accurate
answer, and if you think it's not close enough, it's open source, so
fix it".

If you want to see a really well-done (at least in parts, and also
poorly documented but not making claims to the contrary) Python
program, take a look at Twisted Matrix.  It reimplements any number of
features that are already in Python.  An early version of the docs
explained the reason.  It said something like "it may look like we're
re-inventing the wheel, but we have no choice, since the existing
wheel is square and made of glue".

> Does this make any sense to you?  To me, *this* is the nonsense.

I don't see any nonsense.  People who make claims about a program are
the ones responsible for the truth of the claims.  Saying anyone else
is responsible is bizarre.