How to best visualize software systems

  • Use C4 Diagrams
    • C4 Model
    • Used at Spotify - per Spotify engineering blog
    • Used at Atlassian - at least by one of their Principal Engineers


  • Diagramming shouldn't be done using drag and drop tools
    • Ilograph blog
    • Death by PowerPoint - enterprise architecture edition. If you feel your system architecture went completely off the rails, the direct cause might lie in a slide size limitation (of course skipping the organizational and cultural context that allowed this to happen).
    • Don't get me started on Enterprise Architect
  • mermaid.js is absolutely amazing and I use it extensively, even in personal life to aid thinking and planning
    • mermaid live editor
    • Works in Azure DevOps
    • Works only for conceptual diagrams - due to engine limitations, (at least afaik) doesn't really work for software architecture visualizations on the level that requires icons
    • It has some learning curve, and non-technical people might struggle with it