Documentation: Status Quo

[Patrick Ben Koetter]

Greetings,

I've spent the last two weeks working on amavis documentation. Here's a little
status quo:

At the moment I am not writing/rewriting the existing documentation. This will
have to wait. My first goal is to make the exiting docs more useful in terms
of readability (layout/structur/colouring of code examples) *and* migrate all
docs to AsciiDoc to allow for better automated conversion to other output such
as HTML, man pages etc.

Mark's documentation is overwhelming, but it is hard to find the right section
and it is inconsistent in terms of the point of view. Some docs adress
operators, but most look at amavis from a programmers view. Of course that's
no surprise, given Mark's Perl skills. :-)

In the long run I'd like to change that view and create documentation that
looks at configuring amavis from a adminstrator/operatores point of view first
and then – as a second view – complements the docs by sharing developer
insights.

All this said, I spent my time migrating the docs from plaintext to Asciidoc.
If you wonder why I went for AsciiDoc and not Markdown, please read this:
https://asciidoctor.org/docs/user-manual/#compared-to-markdown Personally I'd
like to add that Ralf and I wrote "The Book of Postfix" in Docbook XML by
then. Since AsciiDoc basically is a reimplementation of Docbook as low markup
language we get the power of Docbook and the simplicity of AsciiDoc.

While I go trough the files I also cross-read the existing documentation. This
way I get to know it better and this will (hopefully) serve me well when I
take out to create a structure that puts the bits and pieces into place.

Here's a litte email stand up meeting:

== What have you completed since the last meeting?

- created a branch "documentation" and begun to work in it
- migrated most of the plaintext files to AsciiDoc low markup
- played a lot with AsciiDoc options to come up with a general set that works
  for all files
- ripped the SQL files apart and singled the SQL database import
  statements out
- SQL commands to create a database and tables are now in separate *.sql
  files for easy use
- SQL commands to populate a database with example test data is in a
  separate SQL file
- ripped amavisd-new-docs.html apart and put the sections into separate files
- begun to create/write an introduction into amavis. It's supposed to
  become the intro chapter that links to all other documentation


== What do you plan to complete by the next meeting?

- finish plaintext to AsciiDoc migration
- decide on dropping a few very old documentations. Either remove them
  completely or move them to some kind of archive
- create a list of topics and put them into some structure
  (sections/subsections)
- assign existing documentation to the created structure
- find out what parts are missing
- come up with some kind of roadmap for documentation work


== What is getting in your way?

My laptops CTRL-Key broke the other day. This makes typing real hard. Besides
that I'll probably have to look out for someone, whose experienced at creating
documetation in CI runners. I've zero experience at the moment and while I'd
really like to find out myself, it will probably take too long before I will
find time to figure out. There are no more cycles left in my calendar this
year and January will close down soon as well...

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