Use mermaid and excalidraw for diagrams

[bernardnormier]

I propose to use only mermaid and excalidraw (https://excalidraw.com/) for diagrams, to provide a consistent look & feel to our diagrams.

Mermaid is reasonably easy to use and works directly with markdoc / markdown. But it's quite limited.

Excalidraw is a more standard diagraming tool that produces SVG images.

[ReeceHumphreys]

I am fine with using Mermaid for some of the diagrams but I think we should not use excalidraw, the diagrams it produces just dont look good which results in them looking very out of place given the attention to detail put into the rest of the docs site. I think the diagrams that I made using Figma that were meant to match Stripes style look much better.

Obviously this is more difficult since it would require going into Figma to create them, but I would be happy to do this. We could have a workflow where you create the way you want the diagram to flow in excalidraw and then I can update it to the Stripe style.

Stripe style:

Excalidraw style:

[externl]

Do we have any other examples of what Excalidraw images will look like? I find that the current example looks pretty bad.

[ReeceHumphreys]

Excalidraw's whole aesthetic is "pencil / freehand" looking diagrams which is what I think doesnt work about it. Here is just showing what different shapes look like etc.

[bernardnormier]

I like the Excalidraw aesthetics and Excalidraw is really easy to use by anybody.

Then I find the Stripe-style diagram that Reece pasted above hard to look at (as in painful). Does Stripe really use this grid-style background? It's also a non-starter if we can't easily draw these diagrams.

[ReeceHumphreys]

Excalidraw makes it look like the diagrams were made in MS Paint for a school project; it does not match the aesthetic of the rest of the docs. Honestly, I think they make the site look amateurish. For the Stripe style, we could reduce the color a bit on the grid to make it more subtle.

Yes stripe uses this style of diagram, here is a page with lots of them: https://stripe.com/docs/billing/subscriptions/overview

Obviously this is more difficult since it would require going into Figma to create them, but I would be happy to do this.

This is the only downside of going with the stripe style. We will not need too many diagrams that are not mermaid ones, so I think this is fine. Figma is a pretty easy tool to use, so once we have a few of the Stripe-styled diagrams made, it would be easy to drag and drop the elements around, similar to Excalidraw if anyone else wanted to do it. But also, as mentioned, I am happy to convert excalidraw diagrams into that style so that is easy for people to make still.