https://blog.icepanel.io/2022/11/30/the-model-code-gap
We think this is more of a human/organizational problem rather than a technical one and we have tons of ideas about how to use links to reality to help humans keep docs up to date. For example an object which has had a lot of commit history recently probably needs the diagrams or docs updating.
What if we only cared about http based services and the boundary is at the service layer? A sidecar running alongside your deployed service keeps track of incoming and outgoing network requests. Each sidecar is configured with metadata: The service name, hierarchy -- it belongs to this even larger service, it's this architecture, and using this runtime, ....
Collecting all of this telemetry along with the metadata would allow you to generate a graph of services in the entire system, who their callers are, and what they call, right? Even that's helpful as a starting point, where I can then go in and fill in the details. When I add a new service, it shows up automatically and is flagged for me to review.
This is one of my primary goals with Ilograph[0] because, as you noted, diagrams that are hard to maintain don't get maintained (and very quickly lose value). It takes a three-pronged approach to solving it:
1. Model-based diagramming. All components in the diagram are part of a model. This means components can be used in many different diagrams (called perspectives in Ilograph) and kept in sync. It's kind of like having static type checking for your diagrams.
2. Diagrams are 100% laid out by machine. Diagrams created using drag-and-drop tools are practicably unmaintainable[1].
3. Perhaps most important, the tool has a full IDE with autocompletion to assist with developer ergonomics. Every little bit helps.
[0] https://app.ilograph.com/ [1] https://www.ilograph.com/blog/posts/its-time-to-drop-drag-an...
I'm unsure, as is, how you fix the organizational and human problem: It takes effort to initially create these diagrams, and constant work to keep them updated as systems evolve. How do you make that easier? A more fancy diagram explorer seems... not as useful.