I think this captures the sentiment I have been seeing and feeling myself. Docs and diagrams die because they aren't code. When the code changes, the docs are left behind.
What is interesting here is that mermaid and graphviz could be committed to source control, but I have never seen it done anywhere likely because the burden of drawing/updating is still too high (hence your wysiwyg comment).
I helped implement Mermaid as a part of Apollo GraphQL’s public documentation to address the “docs as versioned artifact with code” challenge. It’s a win, but still another Yak to shave since public docs are a product, not the source code for the internal teams’ use.
