Convert architecture from png to svg and include in documentation

[ccremer]

Summary

• Removes old uneditable png graphic
• Adds SVG graphic. Recommended editor is draw.io (or diagrams.net). This vscode plugin works just beautifully. Or use the online editor at diagrams.net with your Github login.

Checklist

• Keep pull requests small so they can be easily reviewed.
• Categorize the PR by setting a good title and adding one of the labels:
  bug, enhancement, documentation, change, breaking,
  as they show up in the changelog
• Update the documentation.

[ccremer]

Disclaimer: I mainly did this PR for a blog PoC for @akosma :)

[tobru]

Please do not use SVG but instead a format which can be handled by Kroki (https://vshn-kroki.appuioapp.ch/). See https://github.com/projectsyn/documentation/blob/master/docs/modules/ROOT/pages/about/architecture.adoc for an example, easily drawn using http://asciiflow.com/

[ccremer]

Please do not use SVG but instead a format which can be handled by Kroki

What is the reason to use a 3rd party runtime dependency when trying to draw a diagram? tbh SVG seems much easier and accessible than ascii based diagrams. I played around a bit and it comes nowhere near the flexibilities compared to SVG. furthermore, I find ascii based diagram very hard to maintain.

[tobru]

What is the reason to use a 3rd party runtime dependency when trying to draw a diagram? tbh SVG seems much easier and accessible than ascii based diagrams. I played around a bit and it comes nowhere near the flexibilities compared to SVG. furthermore, I find ascii based diagram very hard to maintain.

ASCII diagrams can be easily viewed in every text editor, no need for third party applications. Take a look at the linked example, looks rather nice in text mode and could also be imported and edited in Asciiflow.

We provide Kroki to have a way to easily create diagrams in different formats, we should make sure to use the same tooling in all documentation projects we maintain and all of them make use of Kroki. See https://vshn-kroki.appuioapp.ch/ for an extensive list of supported formats, and https://kroki.io/examples.html for many examples. You could use https://excalidraw.com/ for example if you'd like to have a more visual design tool than Asciiflow offers.

[ccremer]

ASCII diagrams can be easily viewed in every text editor, no need for third party applications. Take a look at the linked example, looks rather nice in text mode and could also be imported and edited in Asciiflow.

Every OS comes with toolings that can at least display SVG, at the least Browsers do that. I doubt we really have the use case that every file needs to be readable by a plaintext editor? Hardly anyone tries to compile Go program without an IDE either.
And my UX with asciiflow was rather just horrible. Can't even move the whole Diagram back into center if copy-pasted at the edge of the "sheet", no scrollbars, etc ... 🤣

IMO ascii diagrams in text also look horrible (yes, also the one in syn), but that's personal taste :)

Mentioning Excalidraw as an alternative for visual design is for me a bias against drawio, I mean both do the same? Remember, this is not about the need to introduce drawio as a dependency (it's not, a lot of tools support SVG), but in general maintainability of diagrams (not just create new diagrams, but also adjust if necessary). Ofc we can rename architecture.drawio.svg to architecture.svg to be tool name independent.

In the end, we need a tool either way. No one edits ascii diagrams by hand. Might as well use the tools that are simple to use. I find ascii diagrams hard to maintain, even with kroki. Furthermore, only a handful of ascii text diagrams are really diagrams in ascii even with Kroki. E.g. Kroki needs an XML file to render a process diagram in BPMN (https://kroki.io/examples.html#bpmn), which can't be displayed as ascii text. Why do we have this "all diagrams should be in ascii" limitation?

However, if the SVG is a blocker, I'm fine with closing this PR.

[tobru]

I personally feel the need to use the same tooling between all VSHN maintained Antora/AsciiDoc documentation. At this time to generate diagrams it's Kroki. As soon as Kroki supports draw.io, we can start using it: yuzutech/kroki#405. (BTW even GitLab adopted Kroki: https://docs.gitlab.com/13.7/ee/administration/integration/kroki.html).

In the meantime: Let's just merge it as SVG now as the work you've done is a valuable contribution to the documentation nevertheless.

[ccremer]

Fine by me, we can revisit this later or anytime.

[akosma]

I know that this PR is closed, but I do not think we need to be that religious about tooling. I would go as far as saying that, if people want to document (and that's already great in itself) they should be able to contribute whatever format they feel most comfortable with. If they like GIMP and want to submit a PNG, that's OK imho. SVGs are better because they look great, and they can be reused in PDF exports too, and look fantastic when printed. And of course, if you feel like using Kroki, then by all means be our guest. But we need people to contribute docs, and as long as the formats they use are open, I think we can (and we should) accept contributions in whichever format. Just my opinion.