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
pgpsKoDn1vmWG.pgp
Description: PGP signature
-- ## List details at http://lists.exim.org/mailman/listinfo/exim-users ## Exim details at http://www.exim.org/ ## Please use the Wiki with this list - http://wiki.exim.org/
