I'll draw those diagrams... on a whiteboard, sans boxes (Tufte). Great for point-in-time communication, less useful as specifications.

I've taken a throwaway approach to diagramming, where I'll produce them more or less on demand for a meeting or presentation, but not think of them as an enduring artifact. PlantUML is my friend here because I can knock out ugly but gets-the-point-across diagrams in 30 minutes before a meeting and check them into source control, so I can then take the bones of older diagrams and rework them for a fresh meeting.

I used to whiteboard for this, but that hasn't carried over well in the remote world. What I miss about whiteboarding though is that you can tell a story as you draw, so whoever's viewing can watch something unfold from a blank slate while I'm walking them through the history of whatever system we're describing. That said, I can make a PlantUML diagram much more correct than a whiteboard.

All that said I too would love for more of that to be automated increasingly through AI. And I suppose it should make sense conceptually, because for me the value of a crafted diagram over an automated one is that no one really wants to look at the insane ERD of an OLTP database or a production object model. They want the digestible high level vision of the important bits, or the bits that are relevant to the conversation taking place. So it's a summarization problem. How to get the right data to produce a correct summary is interesting--I'm sure if I look there's a dozen papers to read on a similar subject :).

For whiteboarding remotely I use https://excalidraw.com. I use it exactly for your use case. I’ve told live stories with it.

excalidraw is great especially the paid product. One of the cases of a very good open core business plan. I hope they do well.

Thank you, I'm going to give that a try!

That's a great approach that has worked for me too. I think plant is a great little system. Not only can you get your point over in a handful of lines of text but I have found out that it is quite easy to generate the plantuml programmatically. So instead of having to keep docs and code in sync you can end up generating your graphs in ci. The upside compared to big diagramming products is that plant requites no boilerplate and you can provably grep and sed most diagrams out of your codebase which is a quite low barrier to entry.

surprisingly, for average crowds, who usually describe stuff in fluffy text, UML-like diagrams suddenly feel like going from VB5 to python3

> Maybe in the not-too-distant future we will have AI grokking large code bases and cranking out accurate, useful, UML diagrams out of it.

> All those diagrams, when they are complete, correct and up-to-date, do convey what they are supposed to convey.

I spent a bit of time prototyping this recently. It's definitely possible. Rational Rose also had the capability to generate diagrams from code though. I don't remember how good it was at the task though. Was Rational Rose just a very bad implementation?

I find the hate in this chat strange because diagrams are incredibly useful when working through complex problems* and then conveying that information to other engineers. My experience over 20+ years is that a huge portion of engineers can't grok complex problems from code alone.

*Most of my projects are optimizing billion+ row databases, micro-service architectures, and various other scaling challenges.

The problem isn't generating UML from code, the problem is generating useful UML from code.

Where those boxes are in relation to each other matters. You can't just randomly throw boxes and lines on the page, you need to arrange them so that boxes that we can tell what things are related by how close they are to each other. Automatic UML doesn't capture that.

Sometime you have complexity in code that needs tobe hidden by default. I don't care about rare error cases most of the time, but automatic UML can't know what is the complexity needed for rare cases and what is complexity you need to show the junior on the first day.. related to this when i'm interested in one error path how do you hide the others?

Then the real killer of both. Next week there is a minor requirement change (new features we always knew were coming and planned for even), and now the code changed. UML doesn't follow that. Either you generate UML and have the above problems. Or you manually update UML in theory, but in practice just let it slide as the week after you know something else will change and you don't nees it today anyway.

> Or you manually update UML in theory, but in practice just let it slide as the week after you know something else will change and you don't nees it today anyway.

I've heard this argument many times, but how is it different from keeping documentation, comments, tests, or the issue tracker up to date?

They all require some discipline, but if the team finds value in any of these things, they would make an effort to keep them synchronized with the code.

Besides, I suggest not falling in the trap of having formal design documents early on in the project's lifetime. Rather start with informal diagrams and sketches, and once the design has mostly settled, switch to something like UML. This would mean it wouldn't require changes every other week.

As for automatically generating, and dynamically arranging diagrams, this is more up to the generating tool than UML. These tools are still stuck using decades old technology at this point AFAIA, but there's no reason that a smarter tool couldn't do the things you mention.

> The problem isn't generating UML from code, the problem is generating useful UML from code.

I would kill for a tool that could output class and sequence diagrams from a project or component. If the format is editable and tools can automatically layout/filter out components, all the better. Right now the main time sink in putting together diagrams is trying to express what's in the code. Once that's in place, we can prune stuff we don't need.

True, though nowadays I use PlantUML (https://plantuml.com/) which is a DSL using which we can create all kinds of UML diagrams. If any changes are to be made I just need to make the incremental changes using the DSL and regenerate the images. It has been very helpful.