One problem with these tools is that even if you manage to get a good layout for a document then as soon as you need to add/remove/update then you have to wrestle with them all over again.

I've used a few of these code-as-diagram products because I dream of a world where technical documentation, including diagrams, are part of the source code of a project. But my experience is that getting acceptable layouts, especially for external distribution but also just for internal use, is arduous.

And that frustration leads to at least two possible undesirable outcomes: the diagrams become unreadable or the diagrams become unmaintained.

To be honest, the idea of code-reviewing the documents during check-in is also a myth. In general the diffs on these kind of documents are extremely difficult to grok. It is almost impossible to meaningfully check the document is correct without rendering it and reviewing the output.

It is the kind of thing I really wish worked. Maybe one day it will become a solved problem.