At 10:52 AM 6/27/97 -0400, Rich Pieri wrote:
>-----BEGIN PGP SIGNED MESSAGE-----
>
>>>>>> "PB" == Peter Bowyer <pbowyer@verity.com> writes:
>
>PB> This must be the most common source of confusion at the present time -
>PB> I wonder if the docs and/or FAQ maintainers might consider reworking
>PB> the relevant sections ?
>
>The confusion is not due to a failure on the documentation. Read through
>majordomo.ora and you will see that it presents clear and concise step by
>step instructions for installing Majordomo and setting up mailing lists,
>including a variety of tests to ensure that everything works correctly and
>what to do if they fail. No, the "confusion" is due to people trying to
>install Majordomo without reading the instructions first. No FAQ or
>rewording of the documentation will help those who need it because they are
>not reading them in the first place.
Uh...the majordomo.ora file is not the "instructions". The instructions are
in INSTALL. There are no compelling suggestions in either the INSTALL or
README files that say "go read that O'Reilly chapter because it will help a
lot". All it says is how it is part of the MIIS book and distributed with
permission of the publisher.
However, I still agree with Rich that people are just not reading the
instructions. A couple months ago I proposed that INSTALL should be
rewritten to emphasize RESEND rather than INCLUDE aliases. Dave Wolfe
basically said "Sounds good; when will you have it ready?". So I finally
went back and looked at the instructions.
Guess what? They are pretty clear (albeit somewhat dry & technical), and
although they mention INCLUDE style first, it is kind of hard to ignore the
RESEND directions that immediately follow. I came to the conclusion that
there is no quick fix that will end all the needless questions. The docs
are certainly not perfect, and they could use a better explanation of
RESEND vs INCLUDE, but it does not change the fact that it seems not
everyone is reading the stuff cover-to-cover.
--bill
PS: In answer to Peter Bowyer's question: yes, we are always interested in
improving the documentation. What did you have in mind? (If you don't offer
concrete examples of what can be improved [& how], then you will just end
up with more of the same.)
|
|
