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

[Steven D'Aprano]

On Wed, 12 Aug 2009 06:24:18 -0700, Paul Boddie wrote:

> On 12 Aug, 14:08, Steven D'Aprano <st... at REMOVE-THIS-
> cybersource.com.au> wrote:
>>
>> 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.
> 
> 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.


> Once everyone has agreed that the
> description of Python on Wikipedia is reasonable, there's not much point
> in editing it, is there? 

And once we're all fabulously wealthy, there won't be any point in anyone 
working any more either!

The problem for your argument is, even if it were correct, not everyone 
agrees the Python article is "reasonable" -- there were three edits made 
since the 7th of this month. And before that, there was a stream of 22 
edits on the 5th, and another 25 edits since the  8th of July. Obviously 
the Python article is still in active development.

Some of those edits were, apparently, vandalism, which gives yet another 
reason why the Wikipedia model is not necessarily the right model to 
follow.


> In contrast, there's a continuous stream of
> people who don't think Python's documentation is that great.

And a great flood of those who think it's pretty good and gets the job 
done adequately, and a trickle of those who think it's perfect just the 
way it is.

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.


>> And the Python time-machine strikes again:
>>
>> http://wiki.python.org/moin/
> 
> And I suggested that the complainants use it as a starting point.

Sorry, I seem to have missed that.


> [...]
> 
>> 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???
> 
> That's quite an attempt to make my position more extreme than it
> actually is. 

Well, you did raise the issue of the sacrifices you were making to report 
these bugs. All I did was exaggerate the attitude a tad.


> I get people asking me to improve my own software, you
> know, and even if I don't have the time or inclination to do what they
> ask, I do spend time discussing it with them. Such people, including
> myself when I'm on the other side of the fence, appreciate more than
> just a brush-off and no: they don't insist that their own time be valued
> above anyone else's 

Then you're incredibly lucky to attract a better class of end-users. In 
my experience, most end-users won't even spend the effort to describe the 
problem they're having beyond "it doesn't work". And they usually 
misspell that.



> (as you would have me misrepresented); they just ask
> that their own efforts aren't treated as having no value because they're
> not part of the "elite" development team. You get various projects doing
> soul-searching about embracing the efforts of non-programmers, and the
> first port of call on that particular voyage is to not treat them like
> idiot consumers whose remarks can only be considered as mere heckling
> while the visionaries act out their flawless production.

A noble vision, but wait until the idiot heckling consumers discover your 
software, then we'll see how much time you're prepared to give them.



> 
> Paul
> 
> 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?


> 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.


> and there'll always be someone queuing up to dismantle anything
> that does get done at the first opportunity. In contrast, I've found
> other groups of people to be grateful for even modest technical
> assistance, and I know that such people are much more likely to get my
> support and input in the future than those who think that it's some kind
> of advantage to have potential contributors run the gauntlet of denial
> (that there are structural problems in their project), skepticism (that
> newcomers can have anything to contribute), discouragement (because any
> solution which doesn't validate someone's technology preferences must be
> criticised) and, indeed, outright hostility.

I'm having trouble parsing the semantics of that sentence, so please 
excuse me for any misunderstandings.

There seems to be a hidden assumption in your sentence that there *are* 
structural problems in the project. Now obviously no project is 
"perfect", and we all know of cases where a group of people immersed in a 
project will become so close to it that they can't see the rotten trees 
for the wood, so to speak. But generally, the people in the project have 
a very good understanding of the project's strengths and weaknesses, 
because they've been living with it for a long, long time, and it's new-
comers, who don't know the tools, don't know the libraries, aren't 
familiar with the conventions, and don't know the reasons for the 
decisions made, who can't see the trees for the wood.

It's not experienced Python developers who write really slow Java code in 
Python, it's Java developers. And I'm sure the opposite occurs too: 
Python developers learning Java for the first time will struggle to write 
idiomatic Java code, and will criticise *the wrong things* because 
they're thinking like Python developers.

You're expecting outsiders to bring in fresh insights that the jaded, 
stuck-in-a-rut locals can't see. Well, it happens. But for every time it 
happens, there's a hundred outsiders who come along and say the 
equivalent of "What, no GOTO? Well this sucks."




-- 
Steven