The diagrams as code is not a one size fit all. I'd use mermaid for some technical things, but it's failing for communication/presentation purposes. You need to have the ability for arbitrary placement, annotations, flow. Mermaid is all fun until you want to connect two previously distant boxes and everything explodes - for long-term documentation purposes it may not even matter, but if I'm about to show it to anyone, I'm going to Excalidraw.
I work on the Mermaid Chart product team and your comment here is extremely relevant to a big project I'm working on that will solve a lot of the problems you mentioned! Would you be willing to tell me more and give your thoughts on our plan for solutions?
If you're open to it, please send me an email at dominic@mermaidchart.com!
I'd be happy to exchange an Amazon gift card for your time too!
