| I once made the mistake of doing a set of rather detailed integration diagrams for an airline I was consulting at. This diagram, which was intended to be a rough snapshot of how the systems interacted, instead became the single point of reference for how everything in the company worked. It was used to justify investment, knock back projects, one PM even tried to use it to dragoon AD into a PCI Compliance project due to a couple of lines on the aforementioned diagram (like this system has cards, line goes to Exchange as it alerts via email and AD is connected to Exchange. AD is now on the PCI hook). It was the first thing I did there, leaving 4 years later. They were still in wide use 3 years after I left and hadn't being updated since they were drawn, not to mention they were flat out wrong in a number of significant ways to start with (either simplified for $REASONS or just didn't find out the real story until a year or 2 later). These diagrams are probably the most impactful thing I've ever done in my career given how long they remained in daily use and the effort to draw them (which was probably a week or two? Took a long time to get the data but the drawing bit was pretty quick). Would code have made them more accurate or likely to be updated? I doubt it.
Would it have made them more useful? I don't think so, the key to them being well understood and useful was mostly in the layout, something that is difficult to control in any generated diagram. I did actually have a go at using structurizr when I was there but it was too much work when compared to knocking out a quick draw.io. Personally these days I make great use of PlantUML / WebSequence diagrams and am very interested in the C4 / mermaid stuff, but I would likely take the approach of the Engineering Manager - please produce diagrams and make them:
1 - accurate and
2 - useful for whatever story you are trying to tell. Do it in code if you can make it work, but as someone in the thread said - this is an old problem and if it was easy it would have being solved in the 90s. That said I've always thought a dependency system would be a good way to express the relationships between systems - you could almost model systems using something like maven poms - but again, it's always too hard to get the scope and resulting view right. |