>>The solution is clear: the distro maintainers should require that all code contributions must come with good docs. When a code submission comes in, the distro maintainers should critically review the accompanying docs, note any shortcomings and constructively ask for improvements from the contributor until the docs are good. <<
Well, that might be asking a bit too much of the programmers, who perhaps don't exactly enjoy mucking about in the lowlands of English grammar and syntax. All I was saying is you should court writers and mid-level programmers with writing skills (not saying I'M mid-level, I'm still learning) to HELP with creating good documentation. When a writer thinks about helping they go to a page where they are greeted by a bug report menu or CSV notices or some such. That's why most of your really good stuff for beginners is on separately created web pages, where writers simply take matters into their own hands. Also fine, not saying it should be different. Again, taking something like Bengt Richter's suggestion as just one example. To me the module docs are almost incomprehensible without good examples. Why not have a button where people could submit nice SHORT examples illustrating otherwise pure theoretical code and geek-speak. Of course, the editors would decide in a survival-of-the-fittest contest which example gets used, but the point is you'd get good free examples this way. In general, I'd be happy to help a programmer with writing if it meant I would learn programming along the way. It should be that easy. rd -- http://mail.python.org/mailman/listinfo/python-list