Architecture as a communication artifact

Architecture is a communication artifact, not just a technical one. Engineers are rewarded for technical output: shipping code, designing systems, solving hard problems. The idea that how you communicate a design matters as much as the design itself feels like a soft skill dressed up as a principle.

If nobody understood it, you failed, not them

Let's say you're in a meeting, walking through a system you've spent weeks designing, and nobody follows it after 20 minutes. The instinct is to think the audience didn't try hard enough, or isn't technical enough.

The truth is that you failed, not them. If your design can't be understood, that's a property of the design, not the audience. The architecture failed its communication requirement.

A system that only one person can understand, maintain, or extend isn't a technical success. It's a liability.

Documentation is part of the work, not after the work

The TDD (Technical Design Document) isn't a checkbox you tick because the process says so. It's the mechanism by which a design becomes shareable. Until it exists as a document, it only lives in one person's head, which means it can't be challenged, improved, or built on by anyone else.

The other half is keeping documentation alive. It's easy to accumulate pages that nobody trusts because the culture never made updating docs part of the work. The result: engineers can't rely on anything written down, so everything depends on finding the person who was there. That's tribal knowledge, and it's brittle.

You are a salesman

If you want a design to actually happen, you have to sell it. Not just explain it. Sell it.

Framing your design around the technology or methodology is rarely enough. What gets it over the line is framing it around the problem it solves, in terms the people in the room actually care about. Engineers have opinions. Stakeholders have priorities. Meeting each of those on their own terms is what creates the opening for change to happen.

The shift is subtle but important: stop leading with what you're building and start leading with what problem disappears if you build it.

Audience determines format

When presenting to developers, go technical and visual. They want to see the diagram, understand the tradeoffs, and poke at the design decisions. Stakeholders are different: five bullet points, readable in five minutes, focused on impact rather than implementation.

Same information. Two completely different formats. The wrong format to the wrong audience is functionally equivalent to no communication at all. A business owner won't read a 30-page architectural document. A senior engineer won't act on five vague bullet points.

Getting the format wrong means your architecture stays in your head, which means it doesn't exist for anyone making decisions about it.

An analogy: house blueprint

You wouldn't build a house without a blueprint. But a blueprint isn't just a technical document, it's a coordination artifact. Architects, electricians, plumbers, and inspectors all read the same blueprint. Each interprets it through their domain. The blueprint is the shared language that makes the whole project possible.

Architecture diagrams work the same way. They're not just records of decisions. They're the medium through which teams coordinate, challenge each other, and build confidence in a direction together.

Without that shared artifact, every conversation about the system starts from scratch. Decisions get re-litigated. Context is lost when people leave. New engineers don't know what was tried and why it was rejected.

The synthesis

A technically perfect design that nobody understands will either never get built, get built wrong by people who misunderstood it, or become unmaintainable the moment its creator moves on.

A well-communicated design, even an imperfect one, gets challenged, improved, understood, and owned by more than one person. That's what makes it survive contact with reality.

The architecture diagram, the TDD, the demo, the five bullet points for the business owner: these aren't the overhead around the real work.

They are the real work. The code is the implementation of a design that already succeeded at the communication layer.