Align on either Markdown or Asciidoc documentation

[sschuberth]

The project currently makes use of both Markdown (4 files) and Asciidoc (22 files) for documentation. For consistency, documentation should be aligned on either format.

[mnonnenmacher]

I would prefer Markdown over Asciidoc for the following reasons:

• Markdown is far more popular for documentation on GitHub, so more developers are familiar with the syntax.
• The two tools I would prefer to render the documentation to a website both use markdown (Docusaurus, because it uses React like our frontend, and because it's used for ORT; mkdocs-material, because it seems more streamlined than Docusaurus).
• GitHub supports rendering Mermaid diagrams in Markdown, but not PUML diagrams in Asciidoc.

One thing where Asciidoc is clearly better than Markdown is the table syntax, that is terrible in Markdown.

[sschuberth]

Another plus-side of using Asciidoc is that it's also what ORT's template reporter uses, so getting familiar with the syntax could be beneficial.

[oheger-bosch]

My preference is Asciidoc, because in my opinion it offers a great balance between complexity and feature richness - meaning that for typical use cases it is easy to use (and learn) while offering really nice functionality. Its syntax is clear and stringent; some quirks of the Markdown syntax have already been mentioned.

I am not familiar with Mermaid, but from looking at the website, I am not sure whether it supports all the diagram types we use in the documentation. For instance, PlantUML supports complex deployment diagrams with default elements for nodes, databases, message queues, etc.

Another benefit I see is the support in tools like docToolchain. Here multiple documents can be combined to generate documentation in different formats, including websites. We use this internally to deploy our arc42 architecture documentation to GitHub pages. Such an approach could be used to solve the problem that PUML is not rendered natively by GitHub.

[sschuberth]

I am not familiar with Mermaid

FYI, I've been enjoying to use https://mermaid.live/ to learn Mermaid.

For instance, PlantUML supports complex deployment diagrams

Whatever diagram tool we use, for me it's (very close to) a must-have that GitHub can render it as part of its documentation. Less preferably, diagrams would only be rendered when deploying a website or so (in case of Asciidoc, maybe using Antora as an alternative to docToolchain).

Also, we should keep in mind that there might be nice features in Asciidoc per se, which however are not supported on GitHub, see e.g. this issue.

For reference, there are also more Markup languages supported we theoretically could choose from.

[mnonnenmacher]

My preference is Asciidoc, because in my opinion it offers a great balance between complexity and feature richness - meaning that for typical use cases it is easy to use (and learn) while offering really nice functionality. Its syntax is clear and stringent; some quirks of the Markdown syntax have already been mentioned.

Are there any specific issues with the Markdown syntax except for tables?

I am not familiar with Mermaid, but from looking at the website, I am not sure whether it supports all the diagram types we use in the documentation. For instance, PlantUML supports complex deployment diagrams with default elements for nodes, databases, message queues, etc.

I don't think we have a big need for complex diagrams, but if Mermaid is good enough for the Kubernetes docs it's probably also good enough for us:
https://www.kubernetes.dev/blog/2021/12/01/improve-your-documentation-with-mermaid.js-diagrams/
https://kubernetes.io/docs/contribute/style/diagram-guide/

Mermaid supports C4 deployment diagrams (comptaible with the PUML syntax):
https://mermaid.js.org/syntax/c4.html#c4-deployment-diagram-c4deployment

Another benefit I see is the support in tools like docToolchain. Here multiple documents can be combined to generate documentation in different formats, including websites. We use this internally to deploy our arc42 architecture documentation to GitHub pages. Such an approach could be used to solve the problem that PUML is not rendered natively by GitHub.

I believe that there is a lot more tooling available for the Markdown ecosystem. docToolchain looks pretty oldschool, but maybe it's styleable. Some examples for Markdown:

• https://docusaurus.io/ (used for the ORT docs)
• https://squidfunk.github.io/mkdocs-material/
• https://gohugo.io/ (used for the Kubernetes docs)

[mnonnenmacher]

As there have been no more comments after my last post, I will make a PR to complete the move to Markdown, this will also make #881 easier.

[sschuberth]

As a status update, currently there are still the following *.adoc files in the repository:

docs/architecture/different_tool_versions.adoc
docs/authorization/authorization.adoc
docs/config/config.adoc
docs/db/db_schema.adoc
docs/development/helm.adoc

[sschuberth]

By now only these are left:

docs/architecture/different_tool_versions.adoc
docs/config/config.adoc
docs/db/db_schema.adoc

[sschuberth]

This was resolved by #1694 (auto-close failed again).