Python evolution: Unease

[Peter Hansen]

Paul Rubin wrote:
> Jeremy Bowers <jerf at jerf.org> writes:
>>So, nobody should have to write the docs because they should already be
>>there, but "somebody" should have to write the docs?
>>
>>You need to think more clearly about the pronouns you are slinging around.
>>Who is this "they" that should write the docs?
> 
> The Python advocates who claim that Python is well-documented and take
> exception to when someone say it isn't.  Their idea of "it's
> well-documented" seems to be "if there's parts that you think are
> poorly documented, feel free to document it".  What kind of nonsense
> is that?  "Python code runs just as fast as C code.  If you think it's
> slower, feel free to speed it up".  "Python's standard library
> includes a database module.  If it isn't there, feel free to add one".
> "Programming in Python cures cancer.  If your cancer doesn't clear up
> when you code in Python, feel free to submit a patch".

I think you're throwing out strawman arguments here.

The key distinction is that "well-documented" is clearly
a judgment call, a personal opinion, while the others
are all measurable absolutes.  (The "as fast as C" one borders
on being an opinion, since most people actually say things that
mean something more like "as fast as I need it to, so C has no
advantage".)

Saying, in effect, as they are, "Python's docs are well enough
documented for my purposes and, I believe, for those of many
other people" certainly isn't nonsense, and saying "and if you
don't agree you should consider improving them yourself
instead of asking me or others who feel as I do" is certainly
not nonsense.

> And no, I don't feel a responsibility to do the missing work, since
> I'm not the one making those advocacy claims.

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?

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

-Peter