[T-Winsnes]

I've often found that diagrams as code is fine for simple things, but once the complexities start adding up, it becomes as much work maintaining the diagrams as it is to main the actual codebase. I honestly think there is little difference in effort required to maintain a diagram in something like draw.io over PlanetUML or ilograph. Time is just spent in different places

Automatically laying out diagrams in a away that makes contextual sense is one of those problems that seems easy, but is actually really hard. If it was easy, everyone would have used dot files and graphviz to generate their diagrams since the 90s

Disclosure: I'm the CTO at hava.io, where we automate cloud environment diagrams, so I'm biased towards automation

[alixanderwang]

This is a problem with the languages, not a fundamental flaw. Well designed GUI can beat poorly designed language, but manipulating text has a much higher ceiling than drag and drop, in terms of speed and comfort/familiarity. Every programmer has their own ecosystem for manipulating text. I can grep, version control, diff, jump with Vim key bindings, search & replace, etc.

The layout engines are very hard. We've been making one [0] for over 2 years now. At first it seemed dubious whether it was possible to beat aesthetics of Graphviz, but we've been designing it to emulate how diagrams might look on a whiteboard drawn by humans. That's a very different heuristic than the theoretical hierarchical cross-minimizations that previous algorithms strive for, and it's yielded good results for a subset of diagrams. With further spot-assist of AI, this will only get better.

[0] not linked to not detract with self-promotion. you can find in my profile if you want

[graphviz]

Thank you for mentioning the aesthetics in graphviz. It's not in any sense optimal; we chose a collection of heuristics meant to get somewhere close to diagrams made by hand (with tools). Some areas can clearly be improved. Even the initial ranking and cycle breaking is not always quite right. Possibly some of the middle stages need to be more aware of groups of nodes. How to draw sets of natural looking curves around obstacles in diagrams still seems to be an open problem, do we even know what to optimize? It's natural to ask if machine learning algorithms will get there first.

[oaiey]

But text has two problems: end users hate it and people cannot see two pages of model/diagram-as-code vs. a visual diagram.

Not everyone is a developer.

[alixanderwang]

That's like saying code has problems because end users hate it -- end users don't see it.

[oaiey]

End users are consumers of the architecture here. Developers, testers, it, manager, customization specialists, customers, auditors,. ..

[alixanderwang]

I think you might've misunderstood. The text generates a visual diagram. Like HTML generates a website. You're not showing customers the text, you show them the diagram. You don't show customers HTML, you show them the site.

[oaiey]

Yeah you are right, i messed up. Indeed it is only the architect who will hate it :)

[manojlds]

Yeah we need DiagramGPT on top to layout things the right way.

[greendestiny]

You can get chatGPT to generate plantUML

[alsfjslkdfgj]

If your diagram is too complex to maintain as code it is too complex to read.

The diagram is not the kindgdom. And it will never be, that's why you see it is so difficult to generate them automatically from the real thing.

...If only we hadn't throw out all the tech writers along with the QA folks when moving to agile.

[dogma1138]

Really? A good example would be a chess board individual moves are easy to read in code (chess notation) a whole board state in the mid game not so much…

[dpritchett]

Depending on your chess engine (e.g. a physical board) a player could reasonably move many times without stopping to update the diagram. Maybe I forgot. Maybe I was in a hurry due to schedule problems. Maybe the diagram editor was offline for maintenance but the chess engine was still open so we kept on playing.

This might soon prove to be A Problem for folks who reasonably yet erroneously expected that each responsible player would of course update the diagram immediately after each move.

[bluGill]

A chess game is over in at most about 60 moves. Sure the game might last for several hundred moves, but by move 60 only a few pieces are left and it is obvious [to experts] what is going to happen. Even in unlimited time controls, the actual time spent one all moves (as opposed to sleeping or doing some non-game activity while waiting for your opponent to move) isn't very long.

By contrast code lives for many decades. While it isn't all modified every day, it is changed often enough.