Bitching about the documentation...

[Steve Holden]

François Pinard wrote:
> [A.M. Kuchling]
> 
>>On Tue, 6 Dec 2005 00:05:38 -0500, 
>>	François Pinard <pinard at iro.umontreal.ca> wrote:
> 
> 
>>>It's a relatively recent phenomenon that maintainers go berzerk, foaming 
>>>at the mouth over forms, borders, colors, and various other mania!  :-)
> 
> 
>>It's largely to ensure that the ideas aren't lost.  E-mail sits around
>>in an inbox until it gets deliberately deleted or gets lost in a disk
>>crash or system upgrade gone wrong.
> 
> 
> Or sorted properly by the recipient, the way he sees best fit, in the 
> tracker of his own choice.
> 
> I know I'm repeating myself, but my point just does not seem to get 
> through.  The maintainer should manage his way as a grown up, instead of 
> expecting the world to learn his ways and manage in his place.
> 
> 
>>You may suggest that I should process my e-mail more promptly.
> 
> 
> No, I'm not suggesting you how to work, no more that I would accept that 
> you force me into working your way.  If any of us wants to force the 
> other to speak through robots, that one is not far from unspeakable...
> 
> 
>>If the message was important, they'll resend it.
> 
> 
> This is despising contributions.  If someone sends me a message which 
> I find important, I do take means so that message does not get lost, and 
> that it will even suvive me for some while.
> 
> 
>>This is why things need to go into public trackers, or wiki pages.
> 
> 
> Whatever means the maintainer wants to fill his preservation needs, he 
> is free to use them.  The problem arises when the maintainer wants 
> imposing his own work methods on others.  Let contributors be merely
> contributors, and learn how to recognise contributions as such and say 
> thank you, instead of trying to turn contributors into maintainers.
> 
François, you talk of "the maintainer" as though each piece of code is 
owned by a single individual. In Python's case this is far from the truth.

So, what you say *seems* to equate to "If there's a problem with Python 
that I think should be fixed, I should be able to mail the person I 
suspect is most likely to maintain that code, and they should be obliged 
to log the bug or enhancement request in the tracking system".

There's also a philosophical question here about who is helping who. One 
might choose to believe that the contributor is assisting the developer, 
by pointing out a defect in the developer's code. One might 
alternatively regard the contributor as a supplicant, who needs the 
assistance of the developer to get a problem fixed. Finally one might 
regard the contributor (who benefits from having Python available) and 
the developer (who gets the kudos of having developed something "cool") 
to be members of a community, prepared to collaborate to achieve 
something that benefits them both.

In the real world people's opinions will have all kinds of other shades 
as well, of course, but as far as *I'm* concerned, if the developers say 
"please contribute bug reports through Sourceforge" then I am happy to 
do so to make sure they don't fall between the cracks and get lost. YMMV.

Obviously the developers are in charge here, but I really don't see how 
putting more load on them by requiring them to collectively be the only 
sources of bug input to the tracking system will help get more work out 
of them.

If you wanted to build a better tracking system than the one on 
SourceForge I could certainly support that, but historically there 
hasn't been much volunteer effort available to switch to something like 
Roundup which might be preferred.

regards
  Steve
-- 
Steve Holden       +44 150 684 7255  +1 800 494 3119
Holden Web LLC                     www.holdenweb.com
PyCon TX 2006                  www.python.org/pycon/