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