← Back to context

Comment by ctvo

3 years ago

Is the next step creating and updating these diagrams automatically? That dream seems to come up and die in cycles over the years, but it may be possible now depending on the compute platform and network appliances you use. This push to automate by doing interesting things, like reading your network traffic (https://www.akitasoftware.com/), could work here.

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.

> 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?

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 finally got a chance to try this, and I'm impressed. I love the interactive examples right on the site. I'm coming from Mermaid[0], which falls more under 'pure diagramming', where as this is...systems diagramming. Thanks for sharing it.

    0: https://mermaid.js.org/intro/

I think this is purely a tech industry problem of move as fast as possible. Other engineering disciplines have detailed diagrams (breakdown of car parts for example and how to put it back together). It is just not a priority in the tech industry. Until regulation forces fines for software bugs or outages there will never be a priority to pay people to maintain documentation.

Automatically generated diagrams seem to be the dream for many of the developers we chat to, however we don't see this working as great as they believe. This is due to "the model code gap" which is where the abstractions we use to discuss software architecture rarely matches 1:1 with the source code. You can read more about this on our blog article below.

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.

  • I'm not sure I understand. A system diagram from source code or infrastructure alone is difficult, but adding some constraints and boundaries may help?

    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.

    • Yeah that makes a lot of sense, we definitely believe there are automated ways to help speed up the modelling/diagramming process. Such as automatically populating certain levels of the model from resources in reality as you described. Possibly integrating with something like backstage.io could also be super interesting. Then you can create diagrams quicker from a pre-populated model.

      1 reply →