[Python-Dev] status of development documentation

[Robey Pointer]

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