I have noticed diagrams are most useful early in thinking, but once things get complex they either become outdated or too hard to maintain. Curious how people here deal with that, do you keep diagrams in sync with code, or treat them as disposable?

I find I end up needing to walk the code to make diagrams of the current state anytime management wants to know what’s going on. It’s the only way my managers seem to understand or accept anything.

It’s a lot of work, as starting over is often easier than reviews and edits. Usually the diagrams are slightly out of date, but good enough to satisfy whoever is looking at it.

I wish I had a better solution. Now I’m wondering I could write something that walks the code for me.

I treat them as sketches, the way Martin Fowler used to describe a UML diagram. They have to be either disposable or treated as a notepad. I reconstruct the full picture only when it's necessary from "sketches". E.g., since Lucid has an infinite canvas, I'll put all my different diagrams on a single canvas, along with little diagrammatic "ideas", "notes", "brain-f$rts", etc.

For a presentation or project documentation artifacts, I can then go thru my sketches and pull bigger pictures together easily. I applied Fowler's "sketch" principle in my own tool ormle.com

I have reverted to using mermaid where we are beyond the ideation phase. Then the mermaid code can live next to the document source, and I need not search for the original diagram file to edit and export. Confluence has a nice mermaid plugin.

That way, the diagram source and

My approach:

Do use diagrams to explain an abstraction, and attach a word to it. Don't use diagrams to represent the exact state of a system.