Diagrams as code is becoming a popular way to diagram software architecture, particularly for long-lived high-level documentation - write the diagram source in a text-based domain specific language (e.g. PlantUML or Mermaid) or a programming language, and render diagrams using web-based or command line tooling. The benefits are well understood - writing the diagram source as text allows for easy integration into software development practices and toolchains, plus the automatic layout facilities allow authors to focus on content. The problem with this approach is that it's easy for diagrams to get out of sync. Enter "diagrams as code 2.0" and the open source Structurizr DSL - a Java-based library providing a way to define a model of our software architecture and the views that we'd like to see, ultimately resulting in a consistent set of diagrams that are generated for us.

“Big design up front is dumb. Doing no design up front is even dumber.” This quote epitomises what I’ve seen during our journey from “big design up front” in the 20th century, to “emergent design” and “evolutionary architecture” in the 21st. In their desire to become “agile”, many teams seem to have abandoned architectural thinking, up front design, documentation, diagramming, and modelling. In many cases this is a knee-jerk reaction to the heavy bloated processes of times past, and in others it’s a misinterpretation and misapplication of the agile manifesto. As a result, many of the software design activities I witness these days are very high-level and superficial in nature. The resulting output, typically an ad hoc sketch on a whiteboard, is usually ambiguous and open to interpretation, leading to a situation where the underlying solution can’t be communicated, assessed, or reviewed. If you’re willing to consider that up front design is about creating a sufficient starting point, rather than creating a perfect end-state, you soon realise that a large amount of the costly rework and “refactoring” seen on many software development teams can be avoided. Join me for a discussion about the lost art of software design, and how we can reintroduce it to help teams scale and move faster.