3 Ideas How to Communicate Your Architecture

Repeatedly software architects tell me that their stakeholders pay no attention to their architecture. One question I always have: Did you actually tell them? An answer I got was that it was discussed with some other team member a year ago. Since architecture is important, they expect such knowledge to spread on its own. Unfortunately, natural spread does not happen. Maybe because "important" is very often steamrolled by "urgent". Maybe because the architecture has subtle complexities which get lost. Thus the proper communication is a task many architects neglect.

(Disclaimer: This is about architectures which affect many people. For a single team, the natural spread can be sufficient.)

How architects should spend their time

This raises the question how much time an architect should spend on communication. Philippe Kruchten, a well known researcher, gave an answer in What do software architects really do? (pdf). The abstract:

To be successful, a software architect—or a software architecture team, collectively—must strike a delicate balance between an external focus—both outwards: Listening to customers, users, watching technology, developing a long-term vision, and inwards: driving the development teams—and an internal,reflective focus: spending time to make the right design choices, validating them, and documenting them. Teams that stray too far away from this meta stable equilibrium fall into some traps that we describe as antipatterns of software architecture teams

So, Kruchten distinguishes between three working modes of an architect. As a knowledge worker, it roughly maps to the input, processing, and output of information.

  1. Internal working: This is the deep work an architect performs, essentially thinking and processing information. It may involve communication if there is a whole team of architects.
  2. Inwards communication: Architects must acquire a broad knowledge. This involves listening, reading, and asking questions.
  3. Outwards communication: Once new information is created, the architect spreads it. This involves presentations, writing documentation, and supporting.

The ideal balance, according to Kruchten, is 50:25:25. So only half the time the architect should spend on developing the architecture. The other half is split in learning about the current state and communicating the desired state.


If the balance is lost, various clichees are the result.

One example are perfectionists, who neglect the outward communication. Kruchten calls it "goldplating" the architecture. While the work product is great, it is obsolete on arrival.


An architect who neglects outward and inward communication works "in an ivory tower". While the work product might be internally consistent and beautiful enough to make the creators arrogant, it is impractical and thus ignored. Especially academics tend to fall into this trap.


If the architect neglects the internal working, the absence of a consistent architecture will show in the overall product. It might consist of well crafted parts but they don't fit together well.


An extreme focus on the outward communication turns the architect into a consultant. While the developers appreciate the support, there is no coherent mind behind the architecture.


In practice there seems to be no extreme focus on inward communication. It might be that such architects produce neither architecture documentation nor do they support the team. So they produce nothing of even superficial value and do not survive for long for business reasons.

Effectively communicating the architecture

Let's come back to the initial question: Why don't people know the architecture well enough? Assuming there is solid architecture, the architect is either goldplating or working in an ivory tower. In both cases, the outward communication is lacking, so more focus should be put there. Here are a few ideas which worked for me.

Asynchronous Communication

I love asynchronous communication. As does Elon Musk, so it must be truly great.

Elon Musk communicates asynchronously

The big advantage of asynchronous communication is that it scales much better. In the case of email, you can copy&paste or forward information quickly. Actually, writing in general scales well. Unfortunately, writing skills are underrated in my profession. Other media like podcasts or videos can also scale, but I rarely see them used in the context of software architecture.

What is used heavily are diagrams. Unfortunately, the focus is too extreme. I have seen lots and lots of architectural diagrams which are incomprehensible because textual explanation was missing. Some diagrams are inherently bad (for example they use inconsistent symbols) but even good diagrams require context.

The slides of great presentations are similar. They were designed to work in a presentation. For example, Steve Jobs' keynotes are legendary. Here is one of the most important moments of them all.

Steve Jobs introducing the iPhone

The slide shows three icons of three relevant technologies. During the next seconds later he announces the iPhone which combines those three technologies into one device. The slide works as part of the narrative context but on its own is useless. If you design slides to also work as a handout on their own, the presentation will suffer for it.

Well, if you remember the presentation the slide works as a reminder though. Likewise, my hypothesis is that most architecture diagrams are only useful as a memory aid. To become an effective communication medium it requires more.

One case of asynchronous communication are architectural decision records and I already wrote about them. In our context here the relevant aspect is that decision records should be comprehensible on their own, so you can give people a link to them and they can learn about an aspect of the architecture on their own. You don't have to explain it to them. This doesn't mean you focus more time on outward communication but you spend it more efficiently.

Regular Newsletter

For the last two years, I sent a weekly newsletter to everybody in my project, which is roughly 250 people. Additionally, a few dozen other people receive it as well because they asked explicitly. This shotgun approach means that at least half of the recipients are not my target audience because they are no developers. However, even managers appreciated it as it gives them an impression of the technical issues in the project. My department head said "please, don't stop writing them!"

The newsletter is composed of whatever crosses my desk during the week. It might a little tool how-to which I felt was not known enough yet. It announces new architectural decision records and upcoming/ongoing initiatives. Sometimes developers learned something they should have gotten from project management weeks ago.

Blogging experience helps a lot for writing such a newsletter. The oldest blog post here is from 2009 and I blogged a few years before that already. The most important part of such a newsletter is to do it consistently.

I use meme pictures. They are out of the ordinary at my work and they actually distract from the seriousness of some information. However, multiple people told me that they only wanted to look at the funny pictures and later realized they read the whole mail. Also, developers appreciate the hacker vibes they know from the internet sites they visit regularly. Some told me, the newsletter was the highlight of their week.

Also helpful is writing scientific papers. Assuming proper reviewing from supportive colleagues, you train to write terse yet correct. My newsletter only contains short summaries but plenty of links for more details. Sometimes I even sneak in some self-promotion, like links to my blog here. (I wonder if you found this via such a link?)

The Universal Language is Concrete

The book Made to Stick contains many ideas to make a message more memorable (sticky). One of them is concreteness and they tell a story about the conflict between manufacturing people on the shop floor and engineers drawing blueprints (page 115). That resembles the architect-developer roles quite well.

The manufacturing people were thinking, Why don't you just come down to the factory floor and show me where the part should go? And the engineering people were thinking, What do I need to do to make the drawings better?

[...] Should both parties learn greater empathy for the other and, in essence, meet in the middle? Actually, no. The solution is for the engineers to change their behavior. Why? As Bechky notes, the physical machine was the most effective and relevant domain of communication. Everyone understands the machines fluently. Therefore problems should be solved at the level of the machine. [...]

The moral of the story is not to "dumb things down." The manufacturing people faced complex problems and they needed smart answers. Rather, the moral of the story is to find a "universal language," one that everyone speaks fluently. Inevitably, that universal language will be concrete.

It sounds remarkably similar to our initial question. Developers might ignore the architecture because it is not concrete enough for their problem at hand. The book strongly suggests that the solution is not that developers should be educated better. It puts the burden on the architects to explain the architecture in concrete situations.

My newsletter reinforces this. Since I need to pump out something every week, I have to pick something small to fill it. Even if it is not relevant to everybody, it nudges me to explain the wider architectural background.

Abstractions are the luxury of the expert. They are shortcuts between well known concrete concepts. If the concepts are not well understood yet, the abstraction is not helpful. So architects should rarely talk about the big overview. At least, keep it short and rough.

All this concrete communication implies a lot of work for the architect in comparison to mere abstract outlines. Remember it should only take you 25% of your time, though. The solution is to use more scalable asynchronous medium and we close the circle to my first suggestion.


If communication has not happened, the burden is (by default) on the sender. If architects notice people do not know the architecture, then they must improve their outward communication. My three recommendations to do that:

  1. Write good architecture decision records.
  2. Write a regular newsletter.
  3. Explain the architecture in concrete circumstances.

Write decision records, write a newsletter, and explain at concrete examples.