camunda-docs
camunda-docs copied to clipboard
camunda
Explore Mermaid for docs diagrams
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.
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?
Ignore BPMN diagrams. I'm thinking anything non-BPMN we should standardize with something like Mermaid.
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.
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
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.