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

Steven D'Aprano steve at REMOVE-THIS-cybersource.com.au
Tue Aug 11 19:53:16 CEST 2009


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


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



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


[...]
>  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;

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

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

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

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

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

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



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

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.


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



-- 
Steven



More information about the Python-list mailing list