System Design as Communication

A system design document is not a technical specification. It's a narrative. It tells the story of how requests flow, where decisions get made, and why trade-offs were chosen. If someone can't follow the story, the design has failed.

I've sat in design reviews where engineers spent an hour explaining their diagram. The diagram had sixty boxes, fifteen arrows, and three different types of lines. By the end, no one understood the system better. The design had failed its primary purpose: communication.

Start with the user's journey. What happens when they click a button? Where does the request go? What systems does it touch? Trace one complete path end-to-end before you show all possible paths.

When I designed my first distributed system, I made the mistake of showing all possible flows at once. The diagram looked impressive, but no one could follow it. My manager asked: "Can you show me what happens when a user creates an account? Just that one flow." I simplified the diagram to show only that flow. Suddenly, everyone understood.

Diagrams are maps, not blueprints

A good architecture diagram answers: "If I'm here, where can I go?" It shows relationships, not implementations. Boxes represent responsibilities. Arrows show data flow. Labels explain decisions.

Avoid overwhelming detail. A diagram with fifty components is a diagram that gets ignored. I've seen teams create beautiful, detailed diagrams that no one uses because they're too complex. The best diagrams are simple enough to draw on a whiteboard.

This diagram answers: "How does authentication work?" It doesn't answer: "What's inside the database?" That's a different diagram for a different question.

The principle is: one diagram, one question. Don't try to answer everything at once. Start with the highest-level question. Zoom in when you need detail.

Trade-offs are decisions, not compromises

When you write "we chose Redis over MySQL for this cache," explain why. What problem were you solving? What constraints did you have? What did you give up?

Good design docs don't hide trade-offs. They explain them. Future engineers will thank you when they need to make similar decisions or understand why something is slow.

I remember a design doc that said: "We use a message queue for async processing." That was it. No explanation. When someone asked why, the original designer had left. We spent a week reverse-engineering the decision. It turned out they chose the queue to handle traffic spikes, but that constraint was never documented. Future engineers couldn't learn from it.

Write the "why" as clearly as you write the "what." Document the alternatives you considered and why you didn't choose them. Document what might change your mind. That context is what makes the next engineer's job possible.

Design for change

The best architecture diagrams show flexibility. They mark extension points. They indicate where new features fit. They show what's stable and what's likely to change.

If your diagram looks like a monolith, ask: "What if we need to scale one component?" The answer should be visible in the design.

I once saw a diagram where every component was tightly coupled to every other component. It was impossible to scale anything independently. When traffic increased, we had to scale everything. The design hadn't considered change.

Good designs anticipate change. They show separation of concerns. They mark boundaries. They indicate what can be replaced without affecting other parts. That flexibility is architecture.

Write for your future self

Six months from now, you'll forget why you made that choice. I know this because I've done it. I've looked at old design docs and thought: "Why did I do that?" The reasoning wasn't there.

Write it down. Document the context, not just the decision. What was the alternative? Why wasn't it chosen? What would change your mind?

I now keep a "decision log" in every design doc. Each major decision gets an entry: what we decided, what alternatives we considered, why we chose this one, and what might change our mind. It takes ten minutes to write, but saves hours of confusion later.

Design documents age. Code changes. But the reasoning behind decisions should be preserved. That reasoning is what makes the next engineer's job possible. That reasoning is what allows you to learn from past decisions.

Use narrative structure

Good design docs tell a story. They have a beginning (the problem), a middle (the solution), and an end (the outcomes). They guide the reader through the reasoning, not just present the result.

Start with the problem statement. Why does this system need to exist? What problem does it solve? Then present the constraints. What can't we change? What must we optimize for? Then show the solution. How did we solve the problem within those constraints? Finally, discuss the trade-offs. What did we gain? What did we give up?

That narrative structure makes design docs readable. It turns technical documentation into a learning opportunity.

Visualize the problem space

Before you design a solution, visualize the problem. Draw the current state. Show what's broken. Then draw the desired state. Show what should be fixed. The gap between those two diagrams is your design.

I've found this technique particularly useful for explaining designs to non-technical stakeholders. They might not understand technical details, but they understand "this is broken" and "this is fixed."

Design at multiple levels

A good design doc has multiple levels of detail. Start with the high-level architecture. Show the major components and how they interact. Then zoom in on each component. Show how it's structured internally. Finally, show the interfaces. Show how components communicate.

Different readers need different levels of detail. Executives need the high-level view. Engineers need the component details. Product managers need the interfaces. One design doc should serve all of them.

Iterate on clarity

Design docs are drafts, not final documents. Write them, review them, and improve them. Ask someone to read your doc and explain it back to you. If they can't, the doc needs work.

I've rewritten design docs three times before they were clear. That's not failure—that's the process. The first draft is for you. The final draft is for everyone else.

Measure communication effectiveness

A good design doc enables action. People should be able to read it and start building, or start reviewing, or start planning. If they can't, the doc has failed.

Ask yourself: "Can someone read this doc and understand the system well enough to contribute?" If the answer is no, simplify. Remove detail. Add clarity. Iterate until the answer is yes.

System design is communication. Good communication tells a clear story. Good stories have a beginning, a middle, and a reason for existing. They guide the reader through complexity, not overwhelm them with it. They explain not just what, but why.

Your design doc is your communication tool. Use it well.