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

[Paul Boddie]

On 12 Aug, 17:08, Steven D'Aprano <st... at REMOVE-THIS-
cybersource.com.au> wrote:
> On Wed, 12 Aug 2009 06:24:18 -0700, Paul Boddie wrote:
>
> > What does the Python entry on Wikipedia have to do with editing the
> > Python documentation in a Wiki?
>
> Good question. I was responding to you mentioning Wikipedia as a possible
> role model for the Python docs.

Yes, but claiming that only a few people want to edit a single entry
on one site (admittedly a popular one) isn't the same as saying that
few people would edit a documentation Wiki covering numerous different
things. A bunch of people edit the existing Python Wiki now, although
there's not that much direction behind it.

[...]

> It's not the people who suggest improvements to the docs that are the
> problem, but the ones who insist that the docs are terrible, but aren't
> willing to do anything but complain. Oh, and trolls like ... I hesitate
> to mention his name in case he has a bot monitoring the list ... first
> name starts with "X" followed by "ah", second name sounds like "Mee" ...
> who even if they make a few good points, they're lost in a sea of insults
> to others, arrogance and self-aggrandisement.

Right, but those good points are still worth taking on board. There
have been Xah Lee posts which have been relatively constructive, but
when the only responses are from people who see the name and can't be
bothered reading the message before issuing a stock "he's a troll"
response, the tone is likely to remain vulgar from that point onwards.
Xah Lee can be quite coherent and rational on comp.lang.lisp, which is
more than can be said for a number of regulars on that group.

[...]

> > P.S. The mention of "social problems" ties in with other remarks made
> > recently, and I've increasingly found it more trouble than has been
> > worthwhile to pursue Python-related matters of late. When one tries to
> > encourage people to participate in improving various things, which
> > usually means the community having to accept a degree of criticism,
> > people claim that it's encouraging "undesirable" influences to point
> > such critics in the right direction instead of showing them the door.
>
> Can you point me to a discussion where this has happened?

I won't name names as in some cases I've corresponded privately with
various people who have been perceived to be "trolls" (as you put it
above) and who have had the "don't talk to them" responses from
various regulars. Some people criticise in apparently unacceptable
ways for their own amusement, but most critics do so because they are
unaware of any better way and aren't aware of the most effective
methods to fix the issues that bother them, and this latter group is
clearly invested in finding solutions because they could quite easily
go and use something else. Certainly, I wouldn't spend my time
repeatedly enumerating the problems with a piece of technology if no-
one were interested in helping me do something about them.

> > When one tries to pursue such improvement matters oneself, people always
> > have something to say about the choice of technology or whether they
> > like the particular background colour being used
>
> You've discovered bike-shedding.
>
> > or indeed have an
> > opinion, typically shallow and negative, about anything but the task at
> > hand,
>
> When you're agitating for change, anyone defending the status quo has
> opinions which are shallow and negative. When you're happy with the
> status quo, possibly even for good, rational reasons and not just because
> you're a shallow-minded, ignorant, know-nothing nay-sayer, it's those
> agitating for change who have shallow and negative opinions. It's such a
> bother trying to determine who is right, so I prefer to just accuse the
> other guy of being shallow and negative rather than try to understand his
> point of view. I find it saves time in the long run.

I can expand what I've written to just about any project,
"improvement" or otherwise, where there may not be an existing
solution that anyone actually supports or is willing to use. And
still, if you give people something they could use (which is better
than effectively nothing), my experience is that in some communities
your work, however trivial, will be appreciated. But I get the
impression that in Python-related communities, it's all "Why didn't
you use XYZ?" or "What a toy!" instead.

[...]

> There seems to be a hidden assumption in your sentence that there *are*
> structural problems in the project.

Let me assume that maybe the barriers aren't really that bad for
Python documentation; that anyone who is really going to care about
submitting something will jump through the hoops and deliver something
that can be merged by the core developers. Even then, there's going to
be a whole class of improvements that won't get made by outsiders and
will fall on the editors to make. Now, more often than not, the people
who are already the most overworked are precisely those in the
position of reviewing and merging changes (as well as making their
own), and surely they will want to delegate some of that work, but
it's the classic pitfall of "delegation failure": they don't have the
capacity to delegate because that just means even more work for them
as a result. Shower such people with trivial change requests or bug
reports about documentation errors, and it's clear that the processes
aren't helping the editors to do more or for an increased number of
people to usefully collaborate.

I'm almost past caring about the documentation - it's useful for most
of what I want it for - because the bulk of the documentation that I
do use concerns the standard library which looks more and more
antiquated and disorganised every time I look at its contents. I don't
see any top-down remedy for this situation - Python 3 didn't even
bother with it properly - and maybe the solution will ultimately
involve a completely independent standard library developed by people
under their own steam who will then be criticised for not choosing the
most permissive licence possible and/or being technologically
backwards in some aspect of what they've done. That would, after all,
be the "Pythonic" response I'd most expect to see.

Paul