Lindsay Haisley writes: > Well-written technical documentation, however, is also somewhat > rarer than one might hope.
True. But Mailman's is well better than average in my experience because about half of it is in the FAQ, based on the Internet tradition of codifying best current practices (ie, summarizing Mailman-Users threads). The basic install and configuration documents are by now third generation (at least; I'm thinking of UCSD listserv and Majordomo). And many of the people involved place high priority on user service, including documentation. > It's almost axiomatic that people with good technical skills are > often verbally challenged when it comes to writing good > documentation, whether it's for the general public or for other > technical people. This has not been my experience. When challenged to write good documentation[1], most can do it, although there are glaring exceptions. The problem is "I'd rather be coding". It's expensive to enforce good documentation practices; you basically have to pay real money for it (or have a charismatic boss like rms or GvR, and even then it only applies to the projects s/he's directly involved in). It's much easier to get "professional users" to contribute this way, and I believe that Mailman (like Apache, for similar reasons) has been rather successful. > In my experience, list admins are generally not as tech literate as > system admins, but for the lists I host they're well above average > in their understanding of email protocols and problems. Sure. My point is simply that, especially if they're not as good as the list admins you associate with, people who don't understand what the FAQ says probably also don't have sufficient grip on the basic ideas of the email system to solve their own problems no matter how good the documentation is. Since they're going to come back to the list anyway, the question is "would time be saved for advisors and advisees alike if the docs were better?" IMHO, having followed this ML for about 5 years now, the answer is "not enough to make a thorough rewrite of the docs worthwhile."[2] Most threads are clearly well-informed by the docs and the FAQ; the people having problems generally just aren't looking at the issue correctly, and once that's explained, a large fraction of threads are wound up in a post or two (including the thank-you note, which is pleasantly more common in this kind of relatively non-technical audience!) Footnotes: [1] Not "excellent", merely "good". [2] It probably will be useful to review them for style and clarity when 2.2 comes out though. ------------------------------------------------------ Mailman-Users mailing list [email protected] http://mail.python.org/mailman/listinfo/mailman-users Mailman FAQ: http://www.python.org/cgi-bin/faqw-mm.py Searchable Archives: http://www.mail-archive.com/mailman-users%40python.org/ Unsubscribe: http://mail.python.org/mailman/options/mailman-users/archive%40jab.org Security Policy: http://www.python.org/cgi-bin/faqw-mm.py?req=show&file=faq01.027.htp
