Social problems of Python doc [was Re: Python docs disappointing]

[Steven D'Aprano]

On Wed, 12 Aug 2009 03:32:08 -0700, Paul Boddie wrote:

> On 12 Aug, 09:58, Steven D'Aprano
> <ste... at REMOVE.THIS.cybersource.com.au> wrote:
>>
>> We know that there are problems. We've said repeatedly that corrections
>> and patches are welcome. We've repeatedly told you how to communicate
>> your answer to the question of what should be done. None of this is
>> good enough for you. I don't know what else you expect.
> 
> Maybe the problem is that although everyone welcomes contributions and
> changes (or says that they do), the mechanisms remain largely beyond
> criticism. Consequently, one sees occasional laments about there not
> being enough people contributing to Python core development and soul-
> searching about the reasons this might be so. If it were insisted that
> changes to, say, Wikipedia were to be proposed by submitting a patch or
> report for perusal by the editors and for future inclusion in some
> version of the project, the whole project would most likely be a shadow
> of its current self, and ambitions of large-scale collaborative editing
> in general would still be ridiculed.

If Python had the tens of thousands of users, and hundreds of trusted 
(for some definition of trusted) editors, then Python could run using the 
same model as Wikipedia. The Wikipedia model is great, and I contribute 
to it myself.

But Wikipedia gets its users from the entire population of web-users, 
because there's something of interest to everyone in Wikipedia. 
Interested in movies? There are Wikipedia pages for you to contribute to. 
Interested in medicine? There are pages you can help with. Interested in 
the history and development of the mechanical pencil? There's probably 
even a page for you. And if there isn't, you can create one.

With tens of millions of web users, it's no surprise that Wikipedia can 
attract thousands of editors. But this does not apply to Python, which 
starts from a comparatively tiny population, primarily those interested 
in Python. Have a look at the Wikipedia page for Python. The Talk Page 
has comments from no more than *eight* people. The History stats suggest 
that, over seven years, only sixty-nine people have made more than a 
single edit to the page, most of them having made just two edits. Just 36 
people have made more than two edits, and some of those are bots. Only 
one user, Lulu of the Lotus-Eaters (David Mertz), has made more than 100 
edits.


> A free-for-all isn't likely to be the best solution for more actively
> edited Python documentation, but Wiki solutions undeniably provide a
> superior "fast path" for edits by trusted users to be incorporated and
> published in accessible end-user documentation. 

And the Python time-machine strikes again:

http://wiki.python.org/moin/


>> > That some of us choose to
>> > invest it somewhere other than Python does not deprive of of our
>> > right to point out problems in Python when we note them.
>>
>> Of course not. But it does mean that you won't be taken seriously, and
>> you have no right to be taken seriously.
> 
> That's an absurd position that has soured the reputation of numerous
> projects. When someone spends the time to write a bug report, they are
> often investing as much time and effort in something that they are able
> to in any productive sense. 

Firstly, in context, I wasn't talking to somebody who had made bug 
reports. I was talking to somebody whose only contribution, as near as I 
can tell, was to loudly complain that there are flaws in the Python 
documentation and insist that somebody else should fix them just the way 
he wants them fixed -- without being willing to even explain how he wants 
them fixed. Possibly the developers are expected to intuit from first 
principles what he wants.

Secondly, the world is full of complainers who won't lift a finger to 
help but demand others help them. It may be unfair to tar everybody with 
the same brush, but life is to short and time to valuable to avoid making 
judgements as to who to pay attention to. Those who invest a lot of 
effort into providing patches get listened to closely; so do those who 
make good quality detailed bug reports. Those who just say "It's broken, 
fix it" don't. Sometimes that will mean that someone with genuinely good 
ideas will be ignored, but that's the price one pays for avoiding being 
drowned by a chorus of trivial, contradictory, vague and insubstantial 
complaints.

If the Python Dev team paid attention to every post here claiming that 
Python "has a bug" when the bug was actually in the complainant's own 
code, we'd probably still be running Python 1.5.


> I make a habit of submitting bug reports to
> software distributions, typically so that the people who are responsible
> for the components involved can investigate the problem effectively.
> When the maintainers just close such reports or mark them with a number
> of different labels which mostly indicate that they consider those
> reports not worth their time, it sends the message that they consider
> their time to be vastly more important than their users, even though
> their users might have set aside an hour of their potentially busy
> schedule which might have meant sacrificing something else that should
> have taken higher priority (like time for sleeping, in my own personal
> experience).

Oh dear me. You mean that they don't agree that YOUR time is more 
important than theirs??? What horrible people they must be, to expect you 
to sacrifice some of your sleep time just so *they* can get some sleep 
themselves!!! Who do they think they are???



-- 
Steven