Documenting and Communicating Architecture

Welcome to Chapter 4: Documenting and Communicating Architecture. This chapter shows how to describe a software architecture so that the right people understand it, and so that the description stays true. It is practical throughout, and it uses one food-delivery platform as a running example, so you can compare each technique on the same system.

An architecture that exists only in a few people's heads is fragile. Nobody outside the room can review it, the next engineer to join cannot learn it, an auditor cannot check it, and it leaves with the people who hold it. Documentation is easy to get wrong in either direction. Teams that write too little lose the reasons behind their structure, and keep having the same arguments. Teams that write too much produce wikis that nobody trusts. So the guiding principle of the chapter is simple: write for the reader. Decide who will use each piece of documentation and what they need from it, write that briefly and accurately, and write nothing else.

The chapter is written for developers, architects and technical leads. It builds on Chapters 1 to 3: the decisions and structures that now need describing. Sections one point five, on stakeholders and concerns, and one point six, on decisions and trade-offs, are especially useful background. And it leads into Chapter 5, which begins the catalogue of architectural styles, described with the tools you learn here.

The chapter has eight sections. Section four point one asks who documentation is for, and how to decide what deserves writing down. The short answer: write by hand what the code cannot tell you, and generate what the code already states. Section four point two introduces the central idea that one diagram is never enough. An architecture is described through several views, each answering the concerns of particular stakeholders. Section four point three turns that into the most widely used practical approach, Simon Brown's C4 model, with four zoom levels and a short set of notation rules that make diagrams explain themselves. Section four point four covers the parts of the Unified Modeling Language, or UML, that architects still use, such as sequence and state machine diagrams, and when their precision is worth the effort.

This diagram from Section four point one helps you decide how to document any piece of information. The upward axis asks whether it can be recovered from the code. The axis along the bottom asks how often it changes. Top left: things the code cannot tell you, which change rarely. Context and scope, quality goals, and decisions with their reasons. Write these by hand, and keep them. Top right: things that change more often, such as container and deployment views. Keep them next to the code, and review them with every change. Bottom right: what the code already states, and changes often, such as class diagrams and API references. Generate these in the pipeline. Never write them by hand. And bottom left: things you can read in the code that rarely change, like the technology stack or the build commands. A brief pointer in a read me file is enough.

Here is the first level of the C4 model from Section four point three: a system context diagram for the food-delivery platform. At the top are the three kinds of people who use it: customers, restaurant staff and couriers. Every arrow is labelled with what they do. In the middle is the platform itself, shown as a single box. It takes orders, takes payment, dispatches couriers and keeps everyone informed. Below are the external systems it depends on: a payment provider, a maps service and push services. At this level there are no technologies or protocols. Those come at the next zoom level, the containers. And notice the key. Every C4 diagram has a title and a key, so that it explains itself.

Diagrams show structure, but they rarely show why. Section four point five covers Architecture Decision Records, or ADRs: short, dated records of one decision each, with a complete worked record for the delivery platform. Section four point six shows how a template such as arc forty-two gives the whole description a standard organisation, so writers know what to cover and readers know where to look. Section four point seven tackles the problem that defeats most documentation: going stale. It covers writing diagrams as text, publishing documentation from the build pipeline, and the ownership habits that keep it true. Section four point eight turns from documents to people: tailoring the message to executives, developers, operations, security staff and auditors, explaining trade-offs, and building consensus when people disagree.

Every technique in this chapter serves one goal: a shared, accurate understanding of the system among the people who build, run, pay for and depend on it. Small, current, owned documentation that lives next to the code beats a comprehensive document that nobody trusts. So if you remember one question from this chapter, make it this: who will read this, and what will they do with it?

You can read the sections in order, or dip into the technique you need today. The whole chapter takes about three hours to read. As you go, compare how each technique describes the same food-delivery platform: as a context diagram, a container diagram, sequence and state diagrams, a decision record and a one-page summary. Each section ends with a few self-check questions. Answer them in your head before you look. When you are ready, take the optional chapter test: twenty multiple-choice questions and two written answers, in about forty five minutes. The pass mark is eighty per cent.

That is the map of Chapter 4. Start with Section four point one, where we look at who documentation is for, and how much of it is worth writing. See you there.