Communicating architecture to different audiences

Communication is the job

An architecture that only its architect understands has failed, however good it is. Decisions shape what dozens of people build, operate, fund and audit, and they work only if those people understand them well enough to act on them and to notice when reality departs from them. This is why the iSAQB curriculum lists communicating the architecture among an architect's core tasks, and why the architect role described in Chapter 1 depends so heavily on interpersonal skills.

The earlier sections of this chapter supplied the material: views, C4 and UML diagrams, ADRs, an arc42 structure and a pipeline that keeps them current. This section is about using that material with people. The core skill is the same in every setting: decide who the audience is, decide what they need to do after hearing you, and give them exactly what that requires, in the form they can take in. Gregor Hohpe's image of the architect elevator (The Software Architect Elevator, 2020) captures the range: an architect rides between the boardroom, where strategy is set in business terms, and the engine room, where systems are built, and must be understood on every floor.

Tailoring to the audience

Every audience has its own concerns, in exactly the sense of stakeholders and concerns, and its own vocabulary and attention span. The table is a starting point; the real skill is asking, before you prepare anything, what will this person decide or do differently after this conversation?

Two habits help with every audience. Lead with the answer. Busy readers should learn the conclusion in the first sentence, then the supporting reasons, then the detail; this is the structure Barbara Minto taught consultants as the Pyramid Principle, and it is the same idea as Fowler's inverted pyramid for ADRs. Use their words. To a finance director, eventual consistency is noise; the restaurant sees a new order up to two seconds after the customer does, and nothing is lost is a fact they can weigh.

Explaining trade-offs

Most architectural communication is, at heart, explaining a trade-off. Non-specialists distrust recommendations that seem to have no downside, and they are right to. A clear structure, used consistently, makes trade-offs easy to follow: the options (including doing nothing), the criteria that matter to this audience, how each option fares, the recommendation and its consequences, including what you are giving up. This is the anatomy of a decision from Chapter 1 and the content of an ADR, reshaped for a listener.

The one-page architecture summary

Every system benefits from a one-page architecture summary: a single page that a newcomer, an executive or a reviewer from another team can read in five minutes. It is not a substitute for the full documentation but the front door to it. A useful structure is: what the system does and for whom (two sentences); the top three quality goals; a system context diagram; a container diagram or a list of the main building blocks; the five or so decisions that shape everything (one line each, linking to ADRs); the top risks; and where to find more. The arc42-lite page in arc42 and templates is one such summary.

The discipline of fitting the architecture onto one page is valuable in itself. If the main ideas cannot be stated in a page, they are probably not clear to the team either.

Storytelling: follow one request

People remember stories better than structures. A powerful technique for explaining any system is to follow one request: pick a single, concrete, important event, such as a customer placing an order, and walk through what happens to it, step by step, across the architecture. A static box diagram shows what exists; the story shows why it exists and how the parts cooperate. It also reveals the interesting moments naturally: where the customer waits, where data crosses a trust boundary, what happens if the payment provider is slow.

Choose the story for the audience. For developers, the happy path then a failure (now the payment provider times out). For operations, the failure and recovery. For executives, the customer's experience with only the business-relevant moments. Number the steps on the diagram so that you can point to them, and keep the same diagram on screen while you talk rather than flipping between slides.

Whiteboarding and sketching well

Much architectural communication happens live, at a whiteboard or on a shared online canvas, and a few habits make sketches far more useful. Say what you are drawing before you draw it (this is the container level: things we deploy separately), so the audience knows the level of abstraction. Start with the context: the users and external systems at the edges, then the inside. Label every box and every line as you draw, including the direction and what flows; an unlabelled arrow will be read in three different ways by three people. Draw a small key in a corner when you use more than one kind of line or box. Leave space, because the best ideas arrive mid-discussion and need somewhere to go.

Sketches are thinking tools and are meant to be thrown away, but the conclusions are not. Photograph the board, and within a day turn anything that will matter into a proper diagram, an ADR or a change to the documentation. Simon Brown, who created the C4 model, observed that many teams' whiteboard diagrams are ambiguous boxes and lines precisely because they lack an agreed set of abstractions; using the C4 levels on the whiteboard is one of the simplest ways to fix that.

Design documents and RFCs

Many engineering organisations use a written design document, often called an RFC (request for comments), to propose a significant change before building it. The name echoes the Internet's RFC series, which began with RFC 1 by Steve Crocker in April 1969. The author writes the problem, the context, the goals and non-goals, the proposed design, the alternatives considered and the cross-cutting concerns such as security, privacy and observability; the document is circulated to the people affected, who comment in writing; and it is approved or revised. Malte Ubl's widely read description of design docs at Google (2020) lists exactly those sections and suggests ten to twenty pages for large projects and one to three pages for small mini design docs. Gergely Orosz described how Uber used an RFC process from its early years to spread knowledge and catch problems early (2018).

Amazon takes writing further: its 2017 shareholder letter explains that the company does not use slide presentations in meetings but narratively structured six-page memos, which attendees read silently at the start. The benefit common to all these practices is that writing forces clear thinking, written comments let quieter and remote colleagues contribute, and the document becomes a record. The risks are also common: long documents nobody finishes, review processes that become bureaucratic gates, and design docs that are never updated after implementation.

Design docs and ADRs complement each other. A design doc explores a problem and proposes a whole design, often covering several decisions; once it is approved, the significant decisions it contains are captured as ADRs, which are shorter, permanent and indexed. A reasonable rule is: design doc to think and persuade, ADR to remember.

Presenting at an architecture review

An architecture review is a meeting in which other experienced people examine a design to find risks before they become expensive. Structured methods such as ATAM and lighter-weight reviews are covered in Chapter 11: lightweight reviews; here the concern is how to present well. Send the material at least two days ahead: the one-page summary, the key diagrams, the relevant ADRs and the quality scenarios. State at the start what you want from the review: approval, a list of risks, or a choice between two options. Present the drivers before the design, because a reviewer cannot judge a design without knowing which qualities it must achieve. Walk through one or two scenarios using the follow-one-request technique, including a failure. Show the trade-offs you made and the risks you know about; a reviewer who finds a risk you have already listed trusts you more, not less. Record every issue raised, with an owner, and send the list afterwards.

Visual design rules for diagrams

Diagrams communicate before anyone reads a word, so their visual design matters. The rules below are drawn from the C4 notation guidance in the C4 model and from general information design. The before-and-after diagram applies them to the same five elements.

Handling disagreement and building consensus

Disagreement about architecture is normal and healthy: it usually means people see different risks. The aim is not to win but to reach a decision that the people who must live with it understand and will support. Several practices help.

Separate interests from positions. We must use Kafka is a position; I am worried we will lose events during deploys is an interest, and interests can often be met in several ways. Agree the criteria before comparing options, as in a weighted decision matrix; most heated arguments are really disagreements about what matters, and they cool down once that is explicit. Resolve uncertainty with evidence: a two-day spike or a load test settles many debates that meetings cannot. Write it down: a proposed ADR or design doc lets everyone comment in their own time and gives quieter colleagues a voice.

Aim for consent rather than unanimity. The IETF's RFC 7282 (Pete Resnick, 2014) describes rough consensus: a decision is reached when every objection has been addressed, which means considered and answered, though not necessarily accommodated. Asking can anyone not live with this, and why? surfaces blocking issues faster than asking whether everyone agrees. When consensus is not possible, someone must decide, and it should be clear in advance who. Jeff Bezos's 2016 shareholder letter popularised disagree and commit: people state their disagreement openly, then commit fully to the decision once it is made. Record the dissent and the reasons in the ADR; if the dissenters prove right, the record shows what to revisit and why.

Two failure modes deserve a warning. The architect who wins every argument by seniority stops hearing about problems. The team that cannot decide without unanimity lets important decisions be made by default, which is the opposite of the last responsible moment.