On 2010-09-24 at 09:47 +0200, a list participant wrote:
> Newcomer asking for help (Fr 24 Sep 2010 06:08:42 CEST):
> >
> > Hi Eximers,
> > The documentation is a little vague.
>
> That's what you say…
The documentation is extensive, but not perfect. Mistakes in the
documentation are a bug, as serious as a software bug; but where the
documentation is factually correct but not entirely clear, we run into
grey areas.
This is especially true for a product which has become widespread in
many countries, with English often being a second, or even a third,
language. Projects with very little documentation have it much easier
here.
If someone says the documentation is vague, then my default assumption
is that they're right, it is vague *for them*, and as the whole point of
documentation is to *communicate* and teach, the documentation is itself
vague and there's a problem. Sure, there will be the occasional person
who simply refuses to read documentation and learn and will always claim
that there are problems, but this is unusual. Please, be gentle with
newcomers who clearly are working to understand.
I second Nigel's comment that patches are welcome. This is serious, not
a dismissal: anyone who can come up with better phrasing for items,
please do submit them. Ideally, you'd work from the source material
from which the various documentation forms are generated. If you (the
general audience) are not happy with that, then I personally am fairly
happy seeing diffs against spec.txt and applying the changes to the
source form (adding markup) myself. [Uhm, as long as the volume is
fairly small, with fixes here and there. If you want to suggest a major
re-working, please work with the source format].
If you've had to puzzle over a part of the documentation, trying to
decipher the meaning, then it is probably a good candidate for
enhancement. Perhaps a change of wording, which is easier for
non-native speakers to figure out; perhaps more examples for tricky
points. Perhaps an expanded sub-chapter working through concepts at a
higher level.
While there's good material in the wiki, it tends towards the how-to. I
for one would be happy to see a new document, perhaps two chapters long
(Exim docs style) which provides a high-level overview of what's going
on, provides some more fully-worked examples and contains plenty of
pointers into various parts of the specification; this document might be
a good candidate for translation.
In part, this overlaps with the Exim4 book. On which topic, I'll point
towards these books:
For Exim itself, as a more tutorial style approach, from the author:
Title The Exim SMTP mail server: official guide for release 4
Author Philip Hazel
Edition illustrated
Publisher UIT Cambridge, 2003
ISBN 0954452909, 9780954452902
Length 595 pages
For sysadmin in general, with a large section of the mail systems
chapter covering Exim:
Title Unix System Administration Handbook
Author Evi Nemeth
Edition 4, revised
Publisher Prentice Hall Ptr, 2010
ISBN 0131480057, 9780131480056
Length 1300 pages
Aka: UNIX and Linux System Administration Handbook (4th Edition)
NB: Amazon rating is five stars.
Disclaimer: I was technical reviewer for the Exim content, but I
receive no compensation by plugging the book.
Regards,
-Phil
