[Python-Dev] status of development documentation

Fri Dec 23 06:58:55 CET 2005

On 22 Dec 2005, at 3:51, Michael Hudson wrote:
> "Fredrik Lundh" <fredrik at pythonware.com> writes:
>>> Checked the python-list archives lately? If you google c.l.python 
>> for the
>> word "documentation", you'll find recent megathreads with subjects 
>> like
>> "bitching about the documentation", "opensource documentation 
>> problems"
>> and "python documentation should be better" among the top hits. 
>> But if
>> you check the bug and patch trackers, you don't find many 
>> contributions.
>> Something's definitely broken.
>> Hmm, it's this discussion again! Let me make my point again!
>> Writing good documentation is hard.

I can only speak for my own experience, but maybe it will help. I 
once tried to help fix a piece of the python docs. The description 
of Py_UNICODE on <http://docs.python.org/api/unicodeObjects.html> was 
-- and still is -- incorrect.
Looking through my mail archives, I sent a patch on 10 October, which 
was apparently taken, but never showed up on the web site. I emailed 
a few reminders, but was eventually told that I should email a third 
person -- who didn't have an email address. At that point I passed 
the level of effort I was willing to put in. :) I think I probably 
put more effort into it than an average person would, so I think the 
barriers of entry are much higher than they should be.
Perhaps something with fast feedback would work a lot better. It 
seems to work well for Wikipedia.
robey