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

[rurpy at yahoo.com]

On 08/12/2009 01:58 AM, Steven D'Aprano wrote:
> 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.

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?  It may be true that some
of the same techniques applicable to maintaining code are
applicable to documentation but I need a lot more than your
assertion to believe they are as equivalent as you seem to be
claiming.

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

That's not refactoring as I understand it -- that is making a
large change.  I don't see that that addresses the problem of
getting a large patch approved or the other issues I mentioned.

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

I'm confused.  If they weren't overworked, then they would
approve patches they didn't see a need for?  Or are you
saying because they are overworked they fail to approve patches
that should be approved?  I am not sure how either supports
the argument that the tracker is the best method of improving
the docs.

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

Has there ever been a PEP for a doc change?  Are you making
a serious suggestion?

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

You are again describing the current process, not the issue
of whether the current process is the optimal one or not.

And while I would never expect a guarantee that a particular
submission would be accepted, I think I would need, if not a
guarantee, at least a high expectation that a submission would
be treated seriously before I invested a large amount of work
in it.

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

Right, this is obvious.  But the other side of that coin
is that if people who see problems with the docs perceive
that those who control access to the docs have no interest in
changing them, then the first group will likely post their
complaints on this newsgroup.  If you don't like that then you
have the same choices you listed above.  Of course if the docs
really are that good, there will relatively few complaints and
the vast majority of readers will recognize the few complaints
as invalid and ignore them, so if you are right that the docs
are good enough, there should be no problem.

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

That fails to explain the repeated criticisms of the docs here
and in blogs.  Of course this argument is not likely to convince
you since there is no reliable quantitative support for the
claim that there are more complaints about the docs than other
aspects of Python -- it relies on each individual's powers of
observation.  But you also have to explain away very specific
criticisms of the docs such as Xah Lee's as invalid or
exceptions.

>> 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 the troll epithet was used
a time or two, but the vast majority were in fact reasonable and
thoughtful responses.  I will try to find some examples from
other past threads.

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

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

And who exactly is this "we" that you are a member of?

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

On usenet no one has a right to anything.  You can take my
posts however you wish.  I've tried to make reasonable arguments
to support my view (with the understanding that these are usenet
posts, not a doctoral thesis).  But you (and the unnamed "we"
above) seem to feel that public complaints or discussion about
better alternatives to the current doc improvement process are
somehow out-of-bounds.  I'm sorry, I disagree.