To me the biggest issue is keeping it all up to date. For that reason I've completely shifted to text-to-diagram tools like PlantUML / Mermaid. As imperfect as they are, they mean you can insist the diagrams are updated in the same commit (or merge request) as the code, and the AI tools are pretty good at working with them too.
I am pretty frustrated at times though with PlantUML / Mermaid. They just do not give enough power to format the diagrams in a human legible way. Am curious what others do for more complex diagrams in this regard.
Comments
To me the biggest issue is keeping it all up to date. For that reason I've completely shifted to text-to-diagram tools like PlantUML / Mermaid. As imperfect as they are, they mean you can insist the diagrams are updated in the same commit (or merge request) as the code, and the AI tools are pretty good at working with them too.
I am pretty frustrated at times though with PlantUML / Mermaid. They just do not give enough power to format the diagrams in a human legible way. Am curious what others do for more complex diagrams in this regard.
Have you tried C4-PlantUML? It actually has functions for manually adjusting the layout when it doesn't do what you want.