Visualise, document and explore your software architecture

on YouTube ↗01h 00m

" summary

Advocates a specific, hierarchical approach: C4 model (system → containers → components → classes), plus lightweight docs-as-guidebook limited to what code can’t show and readable in 1–2 hours. Recommends whiteboards for design, PlantUML/draw.io for diagrams, and an executable architecture description language (Structurizr / open‑source Java and .NET libs) to generate PlantUML/DGML, embed in builds and keep diagrams synced with code. Demonstrates with a real site (TechTribes.je), reports running workshops in 25+ countries for thousands of developers.

AI-written summary · about

" chapters (20)

1. 0:00Visualise, document and explore your software architecture
2. 6:50The primary use for diagrams and documentation is communication and learning
3. 15:54Software architects struggle to communicate software architecture
4. 17:31Do you use UML?
5. 20:25Why is there a separation between the logical and development views?
6. 21:05Our architecture diagrams don't match the code.
7. 23:13We lack a common vocabulary to describe software architecture
8. 28:53A common set of abstractions is more important than a common notation
9. 32:16A model of the static structure forms the basis for other views
10. 35:48Working software over comprehensive documentation
11. 36:45The code doesn't tell the whole story
12. 39:01Describe what you can't get from the code
13. 39:29The scope is a single software system
14. 41:53How do you keep software architecture documentation up to date?
15. 42:32What tools do you recommend?
16. 44:33Text-based diagrams can be version controlled, generated from build scripts, etc
17. 45:26Architecture description languages provide a way to describe architecture as text Darwin, ACME, Koala, Wright, ...
18. 49:32Diagrams are not useful for architectural improvement if they are not connected to the code
19. 50:12Reverse-engineer code to diagrams?
20. 58:31Prefer models over diagrams

" related talks

• 57mVisualise, document and explore your software architectureSimon Brown · NDC London 2017
• 42mSoftware Architecture vs CodeSimon Brown · GOTO Chicago 2014
• 34mDiagram as Code - Decoding Architectural DiagramsNavinya Shende, Tarique Aman Aziz · DevConf.CZ 2025
• 51mDiagrams as code 2.0Simon Brown · JNation 2022
• 54mC4 models as codeSimon Brown · NDC Porto 2023
• 51mConsistent architecture diagrams for C++ projectsMarius Feilhauer · Meeting C++ 2019
• 01h 00mC4 models as codeSimon Brown · NDC Oslo 2023
• 44mAutomate your software design How far we can get and how the AI chanMarcin Samsonowski · Build Stuff 2025