François Pinard <[EMAIL PROTECTED]> writes: > > Let me repeat this for the umpteenth time: You do not have to learn > > LaTeX to contribute to docs. Submit plain text. One of us with > > some LaTeX knowledge will do the markup. Content is the hard part. > > Markup is nothing, so don't let it be a barrier for you. > > More than LaTeX, the main frozener is when people in charge tell you > to use bug trackers to speak to them.
More than latex and bug trackers, the main obstacle is that people wanting better docs want them for the precise reason that the existing docs don't make it clear what the code does. Writing a good doc patch (and the "patches" needed are often sweeping rewrites) requires studying and understanding the code being documented, and the application area that the code tries to implement. Maybe it also requires studying relevant standards that the code implements (to note gaps in the implementation), comparing the implementation to other implementations in other languages, etc. For example, writing a good doc patch for urllib2 would mean checking RFC 2616(?) against the urllib2 code to see what parts of the RFC got implemented and what parts didn't. It might also mean comparing urllib2 with other libraries like LWP (Perl) or whatever the equivalent is in Java. By the time the requester/patch writer gets through studying the code to figure out what it does, maybe s/he has answered his/her own questions and doesn't need docs any more. The person best qualified to know what the code does is the code author, who could answer all the questions immediately. 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. The distro committers are all very skilled and experienced people. So there's a certain amount of mentoring going on whenever a committer works with a contributor to accept a code patch. By communicating what it takes to bring documentation up to snuff, the committers can share their wisdom with contributors and thereby raise the quality standard of not just the distro, but also of the whole contributor community. Passing skills on to others is after all what being a community is about. Many of us who have acquired any skill at putting docs together, acquired them in precisely this fashion, and should try to pass them on. -- http://mail.python.org/mailman/listinfo/python-list
