On 22 Dec 2005, at 3:51, Michael Hudson wrote: > "Fredrik Lundh" <[EMAIL PROTECTED]> 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 _______________________________________________ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
