I've worked with documentation auto-generators before, and the problem they have is that they can't figure out which references are relevant and which aren't. I remember auto-generating a class diagram of a Java project in the late 90's and it showed every class having a reference to the class "java.lang.String". Generators have gotten (a little) smarter with one-off heuristics like "treat the class String as if it were a primitive", but they're still way more cluttered than a knowledgeable human would ever come up with.

Our languages mostly do not have the syntax needed to express higher abstractions. You could create one via meta files or special comment notation perhaps, but it doesn't exist yet (outside of class diagram generators).

A big part of this problem is the "code-model gap".

> Code should generate diagrams automatically as you write it.

That's fine for some purposes, but for general discussions around many subjects (project planning, security, integration testing, etc) you won't get there from generated diagrams out of some code in an application.

How do you do that with disparate, disconnected systems?