Thus spake [EMAIL PROTECTED] 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) | ------------------------------------------------------ Mailman-Users mailing list Mailman-Users@python.org 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