Documentation and Communication
DabbaGo's architect spent a month designing a new delivery-routing system. She presented one huge diagram with forty boxes to the whole company. The CEO asked "so is this going to cost us more?" and the developers asked "which service do I call to get a rider's location?" Neither question was answered by the diagram. The design was good, but nobody left the room understanding it.
The rule
Pick the reader first, then the zoom level and the words.
Architecture that lives only in the architect's head, or in a diagram nobody can read, does not guide anyone. Documentation and communication are how decisions reach the people who must build, fund or live with them. Three habits make them work.
One view per audience. A useful way to organise diagrams is by zoom level, much like a map:
| View | Shows | Best for |
|---|---|---|
| System context | DabbaGo as one box, plus the people and outside systems around it | Leadership, clients, new joiners |
| Containers | The apps, services and databases inside DabbaGo and how they talk | Developers, operations |
| Components | The main parts inside one service | The team that owns that service |
This idea of zooming from context to containers to components is popularised as the C4 model. You do not need every view for every system; draw the ones your readers need.
Keep documents short and close to the code. A one-page overview, the key diagrams and the ADRs, stored in the repository, get read and updated. A 90-page design document on a shared drive goes stale within a month.
Talk in the listener's currency. Leadership thinks in cost, risk, time and customer outcomes. Developers think in boundaries, interfaces and data. Operations thinks in failures, alerts and deployments. The same decision must be explained in each currency.
The shortcut
Before any document or meeting, answer "Who is reading, and what will they do next?" The answer picks the view and the first sentence.
The CEO
Next action: approve budget. Lead with "routes get 15% shorter, saving rider time; it costs six weeks and one extra server". Show the context view only.
The trap is the "everything diagram": one picture that tries to serve every reader and ends up serving none. If a diagram needs a ten-minute explanation, split it by audience.
Drills
Answer fast — trust the rule.
Which view should DabbaGo's architect show a new client who wants to know how their employees' orders reach kitchens?
What should the first sentence to the CEO about the routing system focus on?
Why keep architecture documents short and in the code repository?
A diagram with 40 boxes confuses both leadership and developers. What is the best fix?
Remember
- Pick the reader first, then the zoom level and the words.
- Shortcut: "who is reading, and what will they do next?"
- Trap: one everything-diagram that tries to serve every audience and serves none.