[Python-Dev] status of development documentation (original) (raw)

Robey Pointer 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 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

More information about the Python-Dev mailing list