Help, my diagram doesn't fit on one page!

This definitely goes into the category of a frequently asked question because it crops up time and time again, both during and after my software architecture sketching workshop.

I'm following your C4 approach but my software system is much bigger than the example you use in your workshop. How do you deal with the complexity of these larger systems? And what happens when my diagram doesn't fit on one page?

Even with a relatively small software system, it's tempting to try and include the entire story on a single diagram. For example, if you have a web application, it seems logical to create a single component diagram that shows all of the components that make up that web application. Unless your software system really is that small, you're likely to run out of room on the diagram canvas or find it difficult to discover a layout that isn't cluttered by a myriad of overlapping lines. Using a larger diagram canvas can sometimes help, but large diagrams are usually hard to interpret and comprehend because the cognitive load is too high. And if nobody understands the diagram, nobody is going to look at it.

Instead, don't be afraid to split that single complex diagram into a larger number of simpler diagrams, each with a specific focus around a business area, functional area, functional grouping, bounded context, use case, user interaction, feature set, etc. You can see an example of this in One view or many?, where I create one component diagram per web MVC controller rather than having a single diagram showing all components. You can see this in action in the software architecture diagrams for techtribes.je that are hosted on Structurizr. The key is to ensure that each of the separate diagrams tells a different part of the same overall story, at the same level of abstraction.

Step away from the code!

A short interview with Voxxed

While at the Devoxx UK conference recently, I was interviewed by Lucy Carey from Voxxed about software architecture, diagrams, monoliths, microservices, design thinking and modularity. You can watch this short interview (~5 minutes) at Step Away from the Code! ... enjoy!

The Agile Revolution - Episode 91

Coding The Architecture with Simon Brown

While at the YOW! conference in Australia during December 2014, I was interviewed by Craig Smith and Tony Ponton for The Agile Revolution podcast. It's a short episode (28 minutes) but we certainly packed a lot in, with the discussion covering software architecture, my C4 model, technical leadership, agility, lightweight documentation and even a little bit about enterprise architecture.

Speaking at YOW! in Australia

Thanks to Craig and Tony for taking the time to do this and I hope you enjoy The Agile Revolution - Episode 91: Coding The Architecture with Simon Brown.

Talking with Tech Leads

Or ... how do you deal with people?

A printed copy of Talking with Tech Leads, by Patrick Kua (a Tech Lead at Thoughtworks), arrived in the post this morning. We often discuss the technical side of software development and rarely the “softer” side. This book is a collection of short interviews with people new to or in technical leadership roles. They share their stories, tips and experiences of making that leap from developer to tech lead. To clarify, by "tech lead", Patrick is referring to somebody in a technical leadership role who still writes code. This is synonymous with what I call the software architecture role, with an expectation that part of the role includes coding.

I actually recommend this book during my software architecture workshops as there are some fascinating “eureka” moments presented in the book, especially related to leadership and dealing with people. One of the messages you'll see repeated again and again is that, as software developers, nobody really prepares you for how to deal with people when you make the jump into your first tech lead role. Looking back at my own career and of people I worked with at the time, I'd say the same was true. Hindsight is a wonderful thing, and I wish I had a book like this earlier in my career.

Talking with Tech Leads

I'd certainly recommend taking a look if you're interested in the softer side of the technical leadership/software architecture role. The book is available on Leanpub and as a printed book via Amazon.com and Amazon.co.uk.

Disclaimer: I'm interviewed in the book, as is Robert Annett and a bunch of other people you may recognise ... I receive no royalties for recommending it though. :-)

Two conference keynotes in October

I'm delighted to say that I'll be presenting two conference keynotes during October, both about software architecture and a little bit about microservices.

1. Software Architect 2015 in London, England

The first is titled Modular Monoliths at the Software Architect 2015 conference taking place in London. Sander Hoogendoorn is delivering the other keynote about microservices, and I hope to bring some balance to the discussion by asking this question: "if you can’t build a well-structured monolith, what makes you think microservices is the answer?". I'll also be running a new workshop at the event called Extracting software architecture from code, but more on that later. The Software Architect conference is certainly evolving from year to year, and it's fantastic to see a wide range of topics related to software architecture, design and development.

2. The Architecture Gathering in Munich, Germany

The week after, I'll be presenting another keynote titled Software architecture as code at a new conference in Munich called the The Architecture Gathering. It's a predominantly German language event and the content (from what I understand, and I don't speak German!) looks pretty interesting, as does the list of speakers.

I'm very much looking forward to both, especially as I think we've reached a turning point in our industry where people are starting to think about and appreciate the role that software architecture plays. See you there!

Software Architecture for Developers in Chinese

Although it's been on sale in China for a few months, my copies of the Chinese translation of my Software Architecture for Developers book have arrived. :-)

Software Architecture for Developers

I can't read it, but seeing my C4 diagrams in Chinese is fun! Stay tuned for more translations.

C4 stencil for OmniGraffle

If you like the look and feel of the C4 software architecture diagrams in my Software Architecture for Developers book (see examples here), Dennis Laumen has created an OmniGraffle stencil that will save you some time. Just download the stencil, install and it will appear in your stencil library.

The C4 stencil is available from Omni Group's Stenciltown. Thanks Dennis!

Software architecture workshops in Australia during August

This is a quick update on my upcoming trip to Australia ... in conjunction with the lovely folks behind the YOW! conference, we've scheduled two public software architecture sketching workshops as follows.

This workshop addresses one of the major problems I've evidenced during my career in software development; namely that people find it really hard to describe, communicate and visualise the design of their software. Sure, we have UML, but very few people use it and instead resort to an ad hoc "boxes and lines" notation. This is fine, but the resulting diagrams (as illustrated below) need to make sense and they rarely do in my experience.

Some typical software architecture sketches

My workshop explores this problem from a number of different perspectives, not least by giving you an opportunity to practice these skills yourself. My Voxxed article titled Simple Sketches for Diagramming Your Software Architecture provides an introduction to this topic and the C4 model that I use. I've been running this workshop in various formats for nearly 10 years now and the techniques we'll cover have proven invaluable for software development teams around the world in the following situations:

  • Doing (just enough) up front design on whiteboards.
  • Communicating software design retrospectively before architecture refactoring.
  • Explaining how the software works when somebody new joins the team.
  • Documenting/recording the software architecture in something like a software architecture document or software guidebook.
"Really surprising training! I expected some typical spoken training about someones revolutionary method and I found a hands-on training that used the "do-yourself-and-fail" approach to learn the lesson, and taught us a really valuable, reasonable and simple method as an approach to start the architecture of a system. Highly recommended!" (an attendee from the software architecture sketching workshop at GOTO Amsterdam 2014)

Attendees will also receive a copy of my Software Architecture for Developers ebook and a year subscription to Structurizr. Please do feel free to e-mail me with any questions. See you in Australia!

Diff'ing software architecture diagrams again

In Diff'ing software architecture diagrams, I showed that creating a software architecture model with a textual format provides you with the ability to version control and diff different versions of the model. As a follow-up, somebody asked me whether Structurizr provides a way to recreate what Robert Annett originally posted in Diagrams for System Evolution. In other words, can the colours of the lines be changed? As you can see from the images below, the answer is yes.

Before Before

To do this, you simply add some tags to the relationships and add the appropriate styles to the view configuration. structurizr.com will even auto-generate a key for you.

Diagram key

And yes, you can do the same with elements too. As this illustrates, the choice of approach is yours.

Diff'ing software architecture diagrams

Robert Annett wrote a post titled Diagrams for System Evolution where he describes a simple approach to showing how to visually describe changes to a software architecture. In essence, in order to show how a system is to change, he'll draw different versions of the same diagram and use colour-coding to highlight the elements/relationships that will be added, removed or modified.

I've typically used a similar approach for describing as-is and to-be architectures in the past too. It's a technique that works well. Although you can version control diagrams, it's still tricky to diff them using a tool. One solution that addresses this problem is to not create diagrams, but instead create a textual description of your software architecture model that is then subsequently rendered with some tooling. You could do this with an architecture description language (such as Darwin) although I would much rather use my regular programming language instead.

Creating a software architecture model as code

This is exactly what Structurizr is designed to do. I've recreated Robert's diagrams with Structurizr as follows.

Before “After"

Before “After"

And since the diagrams were created by a model described as Java code, that description can be diff'ed using your regular toolchain.

The diff between the two model versions

Code provides opportunities

This perhaps isn't as obvious as Robert's visual approach, and I would likely still highlight the actual differences on diagrams using notation as Robert did too. Creating a textual description of a software architecture model does provide some interesting opportunities though.