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

[rurpy at yahoo.com]

On 08/11/2009 11:53 AM, Steven D'Aprano wrote:
> On Tue, 11 Aug 2009 07:57:28 -0700, rurpy wrote:
>
>> On 08/11/2009 01:47 AM, Antoine Pitrou wrote:
>>> r<rt8396<at>   gmail.com>   writes:
>>>> On Aug 9, 11:02 pm, David Lyon<david.l... at preisshare.net>   wrote:
>>>>> Since you're talking about documentation, which is a part of python,
>>>>> don't you think you should be discussing it on python-dev ?
>>>> Yea, them's be a friendly bunch to noob ideas ;). Hey i got a better
>>>> idea, lets go to the IRS and see if we can persuade them to stop
>>>> taxing us...
>>> You know, the most interesting thing in this thread is certainly its
>>> title : « Social problems of Python doc »
>>>
>>> Yes, the little social problem here should be clear: if you have
>>> complaints to voice or improvements to suggest to the Python docs, you
>>> should do so on the issue tracker (*). For most topics, this is the
>>> only reasonable way to signal problems to the Python developers
>>> community, and so it is in most free software / open source projects.
>> "the *only* reasonable way"?  That's clearly wrong (unless you want to
>> wiggle in the room provided by "reasonable" or "most"). There is
>> discussion on the dev list, there is discussion here.
>
> Discussion here is spitting into the wind. The noise-to-signal ratio is
> high enough that the people who can fix an issue aren't likely to see it
> here. Unless somebody raises a report in the bug tracker, it will go
> nowhere, fast.

The point isn't always to gain a core developer's attention --
sometimes it is to figure out a good approach before proposing
something concrete.

> The same happens for issues on the dev list: I can't count how many times
> people there have said "put it in the bug tracker, or it will be
> forgotten".

On the contrary, there are many issues raised there that are
discussed there or result in the response, "take it to python-
ideas".  Not every issue to so well-baked that it is ready for
a tracker issue with patch.  There are some things that need
discussion before investing a lot of effort in them.

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

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

>> The big problem with the docs is poor writing (this includes not using
>> examples when they can help explain something more clearly than verbiage
>> alone).
>
> There's a difference between insufficiently good writing and poor
> writing: think of grading the docs, where 100 is "perfect in every way"
> and -100 is "perfectly awful in every possible way". (It's not a linear
> scale.) A score of 0 is "mediocre, just barely acceptable". Poor writing
> has a negative score. In my opinion, Python's docs are perhaps a 40 or
> 50, significantly better than most technical docs I've seen.

There is no objective way of rating docs.  My evaluation results
in part from the fact that I was able to learn Perl using only
the man pages.  I seriously attempted the same with the supposedly
easier-to-learn Python but was not able to and had to resort to
other web resources and buying Beazly's book.

Before you reply that tutorials are for learning, not reference
manuals, I will disagree.  A well written reference manual will
provide all the information needed to understand a language (albeit
arranged differently than the linear form of a tutorial), and I
have learned several languages in addition to Perl from their
reference materials.  Which is why I attribute my failure to do
so with Python to be the docs' fault.

> [...]
>>   I can rewrite some section so it sounds good to me, but likely it will
>> be just as bad (perhaps in different ways) that what is there.
>
> Bug reports are valuable even if you don't have the skills to provide a
> patch. Bug reports with patches are even more valuable, but that doesn't
> mean that the failure to provide a patch *necessarily* dooms your report
> to oblivion.
>
>
>> The post that started this thread proposed something like paying
>> professional writers to improve the docs.  This may or may not be a
>> practical suggestion.  But the immediate response it engendered was an
>> auto-immune-like group response: the docs are great already, don't
>> complain, fix them yourself, yada, yada; the same response that any
>> criticism of free software produces.
>
> I haven't seen any such knee-jerk responses. What I've seen is a set of
> sensible, *practical* advice:
>
> - complaining on its own, especially here, is pointless;

I don't think that is true.  (Or rather, the extent that it is true
is determined by the attitudes here.)

> - Python is a community effort, if you see something that needs fixing,
> do something about it;

Pointing out something that needs fixing *is* doing something
about it.  Maybe not as much as you'd like but from each according
to his ability...

> - many of us DON'T want arbitrary people "correcting" the official docs
> without oversight, and believe that would be a disaster (arbitrary people
> aren't give check-in privileges to add code to Python's standard library,
> nor should they be given check-in privileges to add docs);

Agreed.  I hope that was clear from my earlier post.

> - 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.
However, were the Python docs site to provide a wiki, along
with a mechanism to migrate suggestions developed on the wiki
into the docs, it might well be a viable (and easier because of
the wysiwyg effect) way of improving the docs.  As other have
pointed out, Postgresql, PHP, and Haskell have done so.
Now maybe there are good reasons not to do that.  But your hand-
waving is not one of them.

> - bug reports and patches to the docs are ALWAYS welcome, even if they
> are rejected;

Of course.  The cost for briefly looking at a report before
rejecting it is very low.  However the cost for producing it
can be much higher.  I'm not saying that that is what happens,
just that your statement considers only the pov of the issue
handlers, not the submitters.

> - if you don't have the skills to fix a bug (including doc bugs), an
> alternative is to pay somebody else to do so instead.

That there are alternatives was not my point.  My point was
that there are perhaps *other* alternatives too, but anyone
who tries to explore them here usually gets buried under a
mass of negativity.

>> It's really too bad the the python community can't seriously discuss
>> ways to improves the docs.  There are other possibilities for instance
>> the Fedora Docs project (can't say I'm impressed by what they've
>> produced but that doesn't mean their model is useless).  There is a need
>> for an approval process managed by someone who actually understands what
>> good technical writing is.  And perhaps editors who can polish or work
>> with programmers who provide the raw technical description of some
>> module.
>
> Yes, you're correct.
>
> [sarcasm] Now that we've agreed on what needs to be done, the problem is
> solved!!! [end sarcasm]

Anyone who's ever been to AA knows that the first step to
solving a problem is to acknowledge the problem exists.
As long as every "the docs sux" complaint is met here with
the standard responses that I've mentioned, rather than, "yes,
they do have some problems, what do you think we should do
about them?", the docs will continue to sux.  But as I said
maybe that's just the way it is.

>> Some kind of higher level more global process is the only way I can see
>> that the docs will be improved to any sort or professional standard.  I
>> don't see how issues like this will be addressed by submitting tracker
>> items.
>
> You want community input into the docs, but you're not willing to give
> that input except to bitch and moan and sook that the tracker is no good.

I have not done any "bitching and moaning".  I tried to
explain a group reaction that affects python negatively
(IMO) by rejecting any consideration of ways of improving
the docs other than submitting tracker issues.
That you pejoratively label it "bitching and moaning"
I count as evidence supporting my view.

> Even if the PSF had a full-time team of professional documentation
> writers and editors, guess what, you would STILL need to submit issues to
> the bug tracker, because otherwise THEY WON'T BE TRACKED.

Maybe, maybe not.  Depends on what development process the
(hypothetical) doc team chooses to use is.

>> Personally, I have given up on this issue.  The social factors involved
>> really pretty much determine that the Python docs will never reach a
>> very high quality -- that's just the way it is and I've come to accept
>> that.
>
> Ultimately it boils down to two factors:
>
> Money.
>
> Effort.
>
> 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.  So clearly you are
wrong in the general sense.  Before you call me a free-loading
ingratiate consider the software you use and how much of it you
have made substantive contributions to.  We all have limited
time and resources and we all have to choose where to invest that
time.  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.