[Mailman-Users] TFM & black hole syndrome

[Amanda]

jgo wrote:

> > I really don't think RFTM is rude -- it's reality.
> > If more people did it there'd definitely be less general
> > confusion and that's, in fact, what the docs are for
> > -- issues such as this.
>
> Yah, the trick these days is figuring out which manual.
> With mailman, we have mailman itself, python, sendmail
> (or whatever), Apache (or whatever), several operating
> system variants (with their own file tree & permission
> schemes) & shells.
>
> What is TFM for mailman?  Is it the admin web page,
> list manager page, the READMEs, or something
> completely different?

Well, and then there's the fact that TFM is, generally speaking: fragmented,
incoherent, written from the developer's perspective (rather than the
administrator's), not entirely up-to-date, not comprehensive, rarely up to
technical writing standards, and not always even in standardized English
(American or British, I care not which).

Now, I'm one of those people who's sort of BT and DT. I am told that I have an IQ
that has given fits to standardized test makers. I held a MENSA membership for a
while (until the novelty wore off). I solve intricate logic puzzles for fun. I've
written, QA'ed, and had to support both code and technical documentation for all
sorts of weird things written by all sorts of people. I have also taught subjects
ranging from kindergarten to continuing coursework for educators (most of whom
had masters, and many had doctorates), and therefore had opportunities to read
samples of writing from a wide and wild assortment of sources. I've been "doing
computers" (as my mother says) for more years than I care to count, and hopefully
therefore have at least a bare foundation of essential knowledge in the subject.
I must tell you, my first experience with Linux software documentation gave me a
migraine. It wasn't worth the energy used to display the FM on the screen. I
understood less after reading it than before. My allergy to this bizarre and
unhelpful genre of "writing" is not getting much better with the passage of time.
If I can't understand it ... well, I feel sorry for my former boss, who was
certainly no dummy and picking things up fast, but wouldn't have stood a chance
with those worthless docs...  I've long been tempted to hand one of these
products to a group of ten-year-olds and have then write the tech manual for it,
because their writing is, on average, more insightful, logical, and easy to
follow.

Having vented that little bit of spleen, I have to say that the Mailman docs are
less offensive than most. :-) I suppose one also gets what one pays for: if I had
forked over for Mailman the kind of dough I just forked over for a certain other
piece of software, and had the manual for that software read like the Mailman
documentation, I might have asked for my money back. (By contrast, if the manual
for that software had read like, say, the Sendmail docs, I'd have sued for
damages and emotional pain and suffering.)

So, for all the folks out there who've read everything, tried to make sense of
it, failed, and asked an even remotely intelligent question of his or her peers,
only to be told to RTFM, I stand up and say: Bullpuckey. Reading the FM is not
always sufficient to answer one's questions. Too, even the best and brightest
system administrator has days when he or she cannot see the forest for the trees
- perhaps due to too little sleep, too much caffeine, too many interruptions, too
many days beating one's head against the same recalcitrant problem, or simply the
daily communications gap that occurs from people's differences in connotations
and grammar - and having a peer point out the obvious missing piece is far more
productive (and less insulting) than having that peer tell him/her to RTFM. Gods,
it's like Microsoft tech support! Surely we can do better than that.

::getting down off soapbox and returning to work::

=)
Amanda