Explore Mermaid for docs diagrams

[akeller]

Our docs diagrams are images from various powerpoints and themes/colors associated with Zeebe, Camunda Cloud, and Camunda Platform 8 branding. There are also concerns about these diagrams not being accessible and in most cases, don't include a high-quality text description.

Instead of UML, @Sijoma suggested Mermaid. While separate from Kubernetes, it's the identified way to make diagrams in the Kubernetes style guide.

There are a few issues and requests for Docusaurus to include Mermaid, particularly after GitHub now supports it. For now, we can use this - https://github.com/sjwall/mdx-mermaid.

Additionally, there is a Discourse plugin for Mermaid. Theoretically, this would allow our contributor and developer community ecosystem to standardize on Mermaid for diagrams.

[akeller]

@pepopowitz thoughts on Mermaid?

[pepopowitz]

I think it's neat! We played with it a bit at my previous job, but nothing very deep. I love the idea of diagrams-as-code, though.

The biggest concern I have is if Mermaid fully covers the diagrams we have. I can't tell very easily from their docs if we can/how to extend it if we find that there are shapes/concepts it can't draw that we need to render, say, a BPMN diagram.

But also, would that be a blocking issue? If we can cover 80% of our diagrams with Mermaid but 20% of them can't be drawn, do we leave the 20% as images and consider it a win until we can find/build a way to convert them?

[akeller]

Ignore BPMN diagrams. I'm thinking anything non-BPMN we should standardize with something like Mermaid.

[akeller]

I'm thinking more about the architecture diagrams like the one here or the variety here.

[pepopowitz]

Happy to ignore. It'd be a nice experiment to try to re-draw a few of them with Mermaid at https://mermaid.live/

(Unimportant SEO note: that's not the first result in my search for "mermaid playground". This is.

[akeller]

Keeping in line with scoping things small and iteratively, the definition of done for this issue should be:

• Plugin is enabled
• One example is provided in the docs
• Docs-on-docs info is available in the repo for further use

[pepopowitz]

Keeping in line with scoping things small and iteratively, the definition of done for this issue should be:

• Plugin is enabled
• One example is provided in the docs
• Docs-on-docs info is available in the repo for further use

1 & 2 will be done in https://github.com/camunda/camunda-docs/pull/3549!

When/if that's merged, all that will remain on this issue is docs-on-docs.