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

[Steven D'Aprano]

On Tue, 11 Aug 2009 14:50:51 -0700, rurpy wrote:

>>> The issue tracker is fine for many things, but the process it provides
>>> is equivalent to peep-hole optimization.  How does one submit a
>>> tracker issue for something like the overall organization of the docs
>>> (for example, the mis-placement of things like data- types in the
>>> library manual rather than the language manual)?
>>
>> The same way you would submit a tracker issue for anything.
>>
>> "Documentation bug: Data types are misplaced in the library manual
>> instead of the language manual.
>>
>> Suggested alternative: move page docs.python.org/xyz.html to abc.html"
> 
> But that's the problem.  Such a reorg is not a simple matter of moving a
> file from here to there.  It will require a lot moving about of sections
> and a lot of word-smithing to glue them back together again in a
> coherent way.

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.

In some order:

Consensus that there is a problem that needs solving;
Volunteer(s) to do the work;
Somebody to take responsibility to check the changes in.


Sometimes, in the face of apathy or disagreement (which may very well be 
justified), you have to at least partly solve the problem *before* people 
will agree that it needed to be solved. Welcome to the real world.



> A tracker issue, even one that was fairly specific about how things
> should be reorganized but which did not provide all the needed changes
> (a large patch) would almost certainly be ignored or rejected.

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.



> But
> providing a large patch raises two questions.  How likely is it to be be
> accepted? (Something anyone would want to know before investing the
> time.) And how to actually do the work needed to generate it (it could
> be a very large amount of work for an individual and I don't think it
> can be broken down into small independent issues.) How is one to test
> the waters as to acceptability, or solicit help, if one simply submits a
> tracker issue?

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

You also have to get attention from those with check-in privileges. If 
they approve your patches, you're done. If they don't approve them, or 
fail to respond, you can try convincing them, or taking it to the Python-
Dev list and request somebody review your patches.

If you have no patches, perhaps because you're unwilling to invest the 
effort without a guarantee that it will be treated seriously, then you 
need to get some sort of consensus among the relevant people that the 
problem is worth solving.

Guess what? Sometimes others will disagree with you. What you see as the 
Worst. Docs. EVAR. may be seen as perfectly adequate, even excellent, by 
others. If this is the case, remember, Python isn't your product, you 
don't have veto over what goes into it. Feel free to publish your 
alternatives. Write a book. Go home and cry into your beer over it. 
Whatever. Sometimes you win, and sometimes you don't.

This is the same process whether dealing with code or documentation.


>> - if people are keen on a Python wiki, then by all means publish one,
>> just don't expect the Python dev team to build and manage it for you;
> 
> As luminous a Pythoneer as Fredrik Lundh set up a documentation wiki to
> collect user contributions but it has faded away.  If he couldn't pull
> it off then I'd say most other attempts without the backing of
> python.org are almost certainly doomed to failure.

Perhaps that's a good indication that a Python wiki *doesn't* fulfill a 
need in the community, and that despite what a few squeaky wheels think, 
the docs *are* doing a good job?



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


> rather than, "yes, they do have some problems, what do you
> think we should do about them?", 

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.


>> If you won't put in the effort, and you won't put in the money, then it
>> won't happen. Moaning that other people aren't putting in the money to
>> hire team of professional writers isn't productive, and moaning that
>> other people aren't putting in the effort to improve the docs isn't
>> either.
> 
> Eh?  I have a computer filled with software that I put no money or
> effort into, yet there it is.  

Ah yes, I'm sorry, I missed one other alternative: sit around and wait 
for somebody else to put in the money and/or effort.

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



-- 
Steven