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

[Paul Boddie]

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.

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. Almost every analysis
of the current (and previous) documentation mechanisms has identified
the editorial workflow as a bottleneck and then proceeded to replicate
such a bottleneck in any proposed solution. I'm starting to believe
that there's a certain snobbery about Wiki solutions which lead many
people to develop all sorts of short-term, arcane solutions under the
illusion that something super-special and customised is necessary and
that they have to start virtually from scratch in order to cater to
the ultra-special needs of the target audience; by the time they're
done, no-one's interested any more, except to propose the next legacy
system in the making.

[...]

> > 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. 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). Thus, I've had the impression with
some projects that I should be maintaining all sorts of stuff - the
bootloader, the kernel, various desktop applications, Mozilla - all so
that stuff actually gets fixed and that I'm not perceived as just
another user whose bug reports aren't welcome. I don't find this
reasonable at all when in many cases there *are* people getting paid
to do these jobs.

The Python core developers seem more attentive than in various other
projects, but please let us not establish the "delicate genius"
mentality that has infested other projects to the point that any
criticism is automatically labelled as ungrateful whining by people
who supposedly don't use the software, have an axe to grind, and who
are apparent simpletons who don't understand the revolutionary vision
of the project leadership. If you think throwing away goodwill is an
acceptable way of silencing complaints, please take a look at just
about any article about KDE 4 that permits reader comments to see how
much goodwill can be lost and what effect that has on a project's
reputation.

Paul