[Mailman-Users] Custom Sign-Up Form

[Lindsay Haisley]

Thus spake stephen at xemacs.org on Tue, Oct 17, 2006 at 01:24:42AM CDT
> Lindsay Haisley writes:
>  > For a project I'm working on I just de-geeked the Namazu search
>  > engine example page, which used Emacs, FreeBSD and other techie
>  > terms as search word examples.  I replaced all the geek words with
>  > fruits and vegetables.  Everyone understands fruits and vegetables
>  > ;-)
> 
> This is a *great* example of what to do.
> 
> I'm afraid that de-tech'ing the Mailman FAQ, however, is an example of
> what *not* to do.  I think it should by and large *stay* techie.  If
> you get referred to the Mailman FAQ, you are probably a list admin
> with a problem.  In my experience, Mailman does very well at getting
> the straightforword stuff right.  So if you do have a problem, it's
> probably not straightforward.

I quite agree.  I came in on this thread late in the game, so I'm not aware of 
exactly what it is that the original post talked about de-tech'ing.  
Well-written technical documentation, however, is also somewhat rarer than one 
might hope.  Anyone with a technical background, which I have, who's tried to 
set up the Common Unix Printing System (CUPS) from the ESP documentation has 
experienced the bleeding edge of bad documentation.  It's written in 
hyper-geek, which might as well be Latin when it comes to finding out the 
specific meaning of a particular error or the exact steps needed to do a 
particular job.

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 goes all the way back to 
the 80s and beyond, I'm sure.  The user's manual on my first desktop computer, 
a Kaypro-10, was a disaster area.  They'd copied engineering notes and marked 
them up by hand with a pen, and called it a manual.

> Furthermore, email is a large complex system that is *fundamentally*
> dependent on standards, which are inherently techie territory.

Yep, and RFCs are generally clearly written and logically organized.  Any 
documentation which is based on RFCs, and uses their organization as an example 
will probably be OK.

> Sure, the FAQ could be improved.  But it seems to me that there's no
> shortage of help available for admins on the list, if you look at the
> FAQ but don't understand it.

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.

--
Lindsay Haisley       | "Fighting against human |     PGP public key
FMP Computer Services |    creativity is like   |      available at
512-259-1190          |    trying to eradicate  | <http://pubkeys.fmp.com>
http://www.fmp.com    |        dandelions"      |
                      |      (Pamela Jones)     |