[Mailman-Users] Custom Sign-Up Form

[stephen at xemacs.org]

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.