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

[Steven D'Aprano]

On Wed, 12 Aug 2009 20:23:27 -0700, rurpy wrote:

>> That's no different from *any* major refactoring. The exact same
>> problem exists for code as well as documentation. It's a solved problem
>> for code, and it's a solved problem for documentation.
> 
> Huh?  I don't buy this at all.  Code refactoring doesn't change the
> semantics of the program at all -- it simplifies the code that
> implements behavior without changing behavior.  How does this apply to
> revising documentation?  

My apologies, I mis-wrote. Of course refactoring is inappropriate in this 
context. What I meant was a major redesign where the API may change.

Except of course that documentation changes don't need to be concerned 
with backwards compatibility, except possibly to avoid breaking old links.


[...]
>> Yes it would. Most patches are ignored, because the dev team are
>> overworked, and if they don't see the need for a patch, they won't
>> approve it.
> 
> I'm confused.  If they weren't overworked, then they would approve
> patches they didn't see a need for?  

No.

If they're overworked, they're less likely to spend time investigating 
patches which aren't immediately obvious that they're needed.

And additionally, if the patch doesn't appear to be useful, it's unlikely 
to be approved. Why would it be?


> Or are you saying because they are
> overworked they fail to approve patches that should be approved?

Invariably there will be good patches missed because they haven't been 
noticed.


> I am
> not sure how either supports the argument that the tracker is the best
> method of improving the docs.

These are not arguments in favour of the tracker, these are realistic 
issues that any project of non-trivial size have to deal with. Virtually 
every project (not just software projects either) have to deal with the 
fact that there will be more things to do than resources to do them with.


[...]
>> No, submitting a tracker issue is a necessary but not sufficient step.
>> Without a tracker issue, you're very unlikely to have people agree to
>> replace the existing docs with your docs, although a PEP would probably
>> do it. (A PEP is significantly more effort than raising a tracker
>> issue.)
> 
> Has there ever been a PEP for a doc change?  Are you making a serious
> suggestion?

I don't know if there ever has been, but as far as I know, there are two 
ways to get changes approved to Python: informal approval by somebody 
with check-in privileges, or formal approval on the basis of a PEP. If 
you can't get the first, then the second is an option, albeit unlikely.



>>> As long as every "the docs
>>> sux" complaint is met here with the standard responses that I've
>>> mentioned,
>>
>> But they aren't met with such a so-called "standard response".
> 
> I just looked through the first 70 or so messages in this thread and in
> this case I have agree with you, most of the responses were not what I
> called "standard responses".  There was one guy, a Steven D'Aprano early
> on that trotted out the, "it's free software, fix it if you don't like
> it" line, 

And I stand by it. If you're not helping to solve the problem, then what 
exactly are you doing?

Even if you can't provide a patch, provide a bug report. What 
specifically is wrong with the docs? Be specific. Give examples. Explain 
why it is wrong. State your assumptions, e.g. what audience do you 
represent?

If you do these things, you're helping. If you're just complaining, then 
you're not.


>> 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.
> 
> You have been told repeatedly why your insistence that the tracker must
> be the only channel, is wrong.  I don't understand why you can't
> understand that.
> 
> (Generally only those in authority, bosses, parents, police, and the
> like, "tell" others what a situation is and have a right to demand that
> the subject accept it without question. I think you could find a more
> respectful and less authoritarian way of phrasing what you said above
> since you are not in a position of authority over me.)

"You're not my real dad!!!"

In the words of Jesse "The Body" Venture, I'm just telling it like it is. 
The tracker is the only practical way of getting doc changes accepted, 
for those without check-in privileges or the ear of someone with them. Me 
telling you this is no more an expression of authority than me telling 
you that the USA has 50 states.

Of course I could be wrong. My understanding of the facts might be wrong, 
or I may not be in full possession of all the relevant facts. If so, I 
welcome correction.

So please tell me, what other practical ways are there for an 
unprivileged person to get the official Python docs modified?



-- 
Steven