I love it, but I can't help but wonder why I almost never see complete or up to date diagrams in an enterprise or at scale software engineering setting, despite there being so many tools in this space (mermaid, uml, draw.io, graphviz, etc). I wonder what the barrier is or how to make tools like this fundamentally different so that we would see more adoption. This comes up frequently in the context of secure design re…
My take is that it's a bit worse than that: the whole doc tooling scene is a dumpster fire. I want to maintain technical documentation under revision control (same revision control system as I use for source code), and I want to be able to embed diagrams in said documents (also under revision control) and I want to wysiwyg edit those things. Amazingly in 2024 this does not exist.
This kind of effort is sabotaged at every place I've ever worked, usually because product or leadership insists that it moves to confluence, and then predictably this increases friction and no one ever updates those diagrams again. People with "20 years experience in industry" can't be bothered login to github, and in the best case instead of confluence they want lucidchart, where inevitably the whole org is sharing like 3 seats.
Partly this is just laziness or ignorance, but partly it's deliberate overreach into engineering business because there's lots of people who see actual information as a threat to to their preferred narratives (think hype/sales promises/etc). Plus you can't say that you didn't know about a design flaw if there is 6 month old diagram calling out the need for a solution in big red letters. Since a picture is worth a 1000 words, and since a git hash can get a date attached to it, dead-on-arrival docs/diagrams tends to decrease accountability.