[Python-Dev] status of development documentation
robey at lag.net
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
>> "bitching about the documentation", "opensource documentation
>> and "python documentation should be better" among the top hits.
>> But if
>> you check the bug and patch trackers, you don't find many
>> 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.
More information about the Python-Dev