I've been looking at this recently - involved in domain driven design. Finding the right balance is important. The diagram needs to be easy to make right, and

I've been looking at this recently - involved in domain driven design. Finding the right balance is important. The diagram needs to be easy to make right, and ok to throw away. The diagram has to actually reflect the code. Making the code top down should make the same diagram if you backwards engineered it. I can see how keeping the diagram in the repo is good practice because the further documentation is from code - the less realistic it is. I could really see a DIAGRAM.md - where your IDE would convert markdown into a UML diagram(ish). And plop that inside the top level of a software component. https://plantuml.com/class-diagram https://plantuml.com/class-diagram jetbrains and vscode seem to support these diagrams right there ```puml @startuml Class01 <|-- Class02 Class01 <|-- Class04 Class01 <|-- Class06 Class06 <-- Class08 Class09 -- Class10 Class01 : thing Class01 : Class foo Class01 : speak() @enduml ``` You can pair diagram with the product guy and boom - its in the repo - and easily viewable. I think I might use this.