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

[rurpy at yahoo.com]

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.

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 big problem with the docs is poor writing (this includes
not using examples when they can help explain something more
clearly than verbiage alone).  It is understandable why this
should be so -- most programmers are good at and enjoy
programming, not writing and the python community is, say,
about 99.9% programmers.

This is why all the attempts (at least that I've noticed) are
programming focused -- build a wiki, write a new doc processing
framework, etc.  Unfortunately none of those addresses the real
problem -- the need for clear, well written, well organized
*content*.  I don't see how telling people to submit tracker
issues will solve this problem.  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.

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.

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.

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.

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.