Architecture Documentation

The test of architecture documentation is whether it answers the question someone will actually have in six months. That question is almost never "what are the boxes?" — it is "why is it like this, and what happens if I change it?"

What is worth writing

• Decisions and their rationale (ADRs): context, options considered, choice, consequences. The options rejected are the valuable part; without them the reader re-litigates.
• A context diagram: the system, its users, and the things it talks to. Almost never wrong, almost always useful.
• Failure behaviour: what happens when each dependency is slow or gone.
• The invariants: the things that must remain true, which is what a newcomer will otherwise break.

What is not worth writing

Anything the code already says, and anything that will be stale in a month. A class-level diagram maintained by hand is obsolete before it is reviewed.

Industry example

Google's engineering culture leans on the written design document as the primary architectural artefact — a prose document circulated for comment before significant work starts, covering goals, explicit non-goals, alternatives considered and their rejection, and the trade-offs accepted. The review happens on the document, where changing your mind costs nothing.

Two properties do the work. First, non-goals: stating what the design deliberately does not address prevents both scope creep and the later accusation that something was overlooked. Second, alternatives considered: the reviewer's most useful contribution is usually "you dismissed option B too quickly", and that is only possible if option B is on the page.

Failure scenarios

• The 90-page document nobody reads, whose diagrams contradict each other by page 40.
• The wiki graveyard: accurate on the day it was written, misleading ever since, with no date and no owner.
• Diagrams without a legend, where two boxes of different colours mean either different criticality or nothing at all, and only the author knows.

Trade-off

Documentation trades author time for reader time and future optionality. The economics favour writing when the audience is large or the decision is expensive to revisit, and favour writing nothing when the code is the clearest statement available.

Interview question

"You have two hours to document a system you are handing over. What do you write?"