The “You Get One Diagram” approach to architecture documents

I’ve spent too many hours writing pages and pages of architecture docs that nobody ever read.

I’ve joined too many projects with gigantic architecture docs that were outdated and useless.

I’ve seen too many architecture docs that were mind-numbing prose descriptions of what should have been a diagram.

I’m sick of it. My rule nowadays is that each team gets one diagram. That’s the architecture doc. It can be as complex as it needs to be, but there can only be one per team.

Why a diagram?

• A picture is worth a thousand words. Never has that been more true than with architecture docs.
• Nobody wants to sit there and read dozens of pages of prose when they could look at a diagram instead.
• Maintaining all those pages of text is a nightmare as little things change gradually over time.

Why only one?

• The chance of outdated info increases exponentially with the number of diagrams, rather than proportionally.
• Eventually two “unrelated” things will need a connection between them that we didn’t foresee.
• Onboarding and planning are easier when we can visualize everything in one place.

You get one diagram. Use it well.