Comment by Xmd5a

I think the main reason why diagrams are not used as often as they should to document code bases is that we developers have to face opposite yet complementary approaches: text based graph specifications (but then the layout's quality doesn't scale with graph size), or GUI based approaches that lead to way better results but are too costly to maintain.

The idea of using machine learning is just a kind of knee jerk reaction to this fact. Maybe we could just throw graphs at a graph neural network and have the model learn all the features we are interested in without listing them explicitly (let alone the rules to decide which to prioritize). It's more an art than a science, really.

Among those listed in these papers[1][2] those I am the the most interesting in, beyond the usual overlap minimization, edge crossing and edge length reduction are the following:

    symmetry/alignment
    hierarchical layouts (subgraphs within nodes)
    Fine-grained control of flow direction (doesn't have to be the same in each subgraph)
    

Those are the features that have constrained the most my search for a diagram engine. Aesthetics (I mean readability) is paramount to using diagrams as documentation IMO. They are not just graphs, they are mental palaces.

A palace's layout must not change if you decide to build an extension. Stability isn't guaranteed with most graph layout algos: add a node and you might end up with a graph that doesn't look like the previous version. Nodes shifts, edges move around. Confusing. There has been research in this direction[3], namely "interactive graph layout". It forces us to move away from a stateless approach to graph generation (graph specification -> picture) and into a stateful paradigm where the previous state of the layout will be preserved to some extent in the new version. With the layout specified as a mixture of previous layout state + constraints I could picture a pipeline where an LLM watches the commit log of some git repo and updates diagrams via semantic reasoning automatically with a 90% success rate, while the remaining 10% is left to the developer to fix.

And there is also "UI-bility". A high degree of customization, being able to plug your own (react,vue,whatever) components into a graph can turn it into a monitoring tool. I wrote an (incomplete) debugger for a go-style channel framework that displays interactions as sequential diagrams, and, although neither D2 nor PlantUML offer this, I had to give up on using the former because it did not provide on-hover tool-tips, which was critical for my use case.

[1] https://nrl.northumbria.ac.uk/id/eprint/16689/1/survey_graph...

[2] in particular chapter 6, https://repository.library.northeastern.edu/files/neu:4f196k...

[3] https://rtsys.informatik.uni-kiel.de/~biblio/downloads/paper...