amavis documentation

[Patrick Ben Koetter]

Greetings!

I'm planning to work on the documentation March 2nd and 3rd and I'd like to
receive feedback on my proposal (see below) until then, so I can see and react
to it.

TIA

p at rick



* Patrick Ben Koetter <p at sys4.de>:
> Good Morning,
> 
> I'm still short on time, but I've been working on amavis documentation now and
> then when time permitted to do so. There are a few changes I want to discuss
> before I take this further:
> 
> == Subproject
> 
> I'd like documentation to become a subproject of the main amavis branch. Being
> reduced to the documentation code only will make it easier to handle all the
> transformation that doc code needs to go through before it becomes available
> in various formats.
> 
> This said I created <https://gitlab.com/amavis/docs.amavis.org> a few minutes
> ago. It holds what I am currently are working on.
> 
> Does anyone feel uncomfortable with the docs becoming a subproject?
> 
> 
> == Coverage
> 
> There already is quite a lot of documentation available. It is focussed on
> functionality and how it was implemented, with a few exceptions (e.g. DKIM)
> where it also explains how to get things done.
> 
> I'd like to put a stronger emphasis on "getting things done". My intent is to
> provide at least as much information as it takes to mobilize people to a point
> where they think: "Hey, I can do that."
> 
> 
> == Structure
> 
> This said I've begun to work on a general "amavis" document that states what
> amavis is and then tries to route readers into the right directions. Ideally
> this will become the main starting point in the future.
> 
> The main directions I'm currently thinking of are:
> 
> Setup::
>     How to install and run amavis on a computer.
> Configuration::
>     How to configure specific aspects of amavis.
> Integration::
>     How to integrate amavis into an MTA.
> Operation::
>     How to work with amavis on a server.
> Understanding amavis::
>     How amavis processes email.
> 
> 
> === Setup
> 
> The setup section will cover what it takes to install amavis on your server if
> you download the sources from our website/repos. Before that it should point
> people to the various distribution specific packages that provide amavis as
> they will probably provide better/simplier integration that works with the
> system from the start.
> 
> 
> === Configuration
> 
> The Configuration section should explain the syntax used to configure amavis.
> It should also tell people how to use routines that help e.g. to read in
> external data (read_hash).
> 
> Now that readers would know about the means they have at hands they should set
> their mind on what they want to do. I'd like to give them $something to read
> into "content policies". Maybe thoughts on filtering, a collection of best
> practices and/or architectural examples to get this or that done. I haven't
> really set my mind on a particular approach yet and I'm open to suggestions.
> 
> Then there should be a part that deals with amavisd.conf. It should explain
> the sections this config file will consist of and what they configure.
> 
> 
> === Integration
> 
> This section should address how people can integrate amavis into their mail
> flow. There are serveral documents there already, but they are very different
> in depth and how much they explain. Some are plain cut & paste from Mailing
> list threads.
> 
> I'd like to update all of them. Working on integration into Postfix myself
> seems natural to me. If someone wants to join in, please raise your voice. As
> for the other MTAs I will try to reach out to others. I've no idea how to
> integrate amavis with Exim. The website says " The last 3.x release was 3.36.
> It is obsolete and should not be used." So I will remove all docs pointing to
> 3.x soon.
> 
> How many people are still using Sendmail? I really don't know and I'd like to
> find out if we should maintain documentation for Sendmail. (If you are a
> Sendmail user, speak up. I'll be happy to maintain docs if it makes sense.)
> 
> Any other MTAs we should address?
> 
> 
> === Operation
> 
> This section deals with daily routines. Stale files in $TMPDIR, reading and
> interpreting LOG, database cleanup/stats etc. pp.
> 
> If you know of something you'd like to find in here, drop me a note or create
> an issue at <https://gitlab.com/amavis/docs.amavis.org/issues>.
> 
> 
> === Understanding amavis
> 
> Understanding amavis aims to give the reader an idea how amavis works. What's
> amavis' system metaphor? What are the steps each message handed over to amavis
> goes through? Why, for example, would amavis unpack a message and it's MIME
> parts *before* it hands it down to various content classifiers?
> 
> Speaking of "classifiers". This section should also set and explain the
> terminology we want to use throughout the project: content filte framework,
> classifier, content classes, policy bank etc. pp.
> 
> One of the goals of this section is to help people create an inner model of
> amvis workings. When things go wrong and they need to debug they should be
> able to walk that inner model and think: "It should be doing this at the
> moment, but it doesn't. What could be the reason why it fails at exactly this
> step?"
> 
> 
> That's it for know. I'm curious about feedback.
> 
> p at rick
> 
> -- 
> [*] sys4 AG
>  
> https://sys4.de, +49 (89) 30 90 46 64
> Schleißheimer Straße 26/MG,80333 München
>  
> Sitz der Gesellschaft: München, Amtsgericht München: HRB 199263
> Vorstand: Patrick Ben Koetter, Marc Schiffbauer, Wolfgang Stief
> Aufsichtsratsvorsitzender: Florian Kirstein
>  



-- 
[*] sys4 AG
 
https://sys4.de, +49 (89) 30 90 46 64
Schleißheimer Straße 26/MG,80333 München
 
Sitz der Gesellschaft: München, Amtsgericht München: HRB 199263
Vorstand: Patrick Ben Koetter, Marc Schiffbauer, Wolfgang Stief
Aufsichtsratsvorsitzender: Florian Kirstein
 
-------------- next part --------------
A non-text attachment was scrubbed...
Name: smime.p7s
Type: application/pkcs7-signature
Size: 4460 bytes
Desc: not available
URL: <https://lists.amavis.org/pipermail/amavis-devel/attachments/20190321/2fcef263/attachment.bin>