Peter Hansen <[EMAIL PROTECTED]> 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. -- http://mail.python.org/mailman/listinfo/python-list
