The Documentation Pyramid

Most architecture documentation fails because it is written at a single level of detail. A 60-page architecture document is comprehensive and unread. A one-page diagram is readable and insufficient. The solution is a pyramid — layered documentation at three levels of detail, each serving a different audience and a different purpose. The reader enters at the level they need and goes deeper only when they must.

1. Level 1: The Overview (1 page) The 5-minute architecture. One page. What the system does, what goes in, what happens inside, what comes out, and what protects it. This level serves executive stakeholders, new team members, and anyone who needs to understand the system without building it. If this page does not exist, every explanation of the architecture starts from zero.
2. Level 2: The Component View (5-10 pages) The major components, their responsibilities, their interfaces, and their interactions. Data flow diagrams, integration surfaces, and technology selections with rationale. This level serves technical leads, integration partners, and the team that will extend the system. Detailed enough to design against. Brief enough to maintain.
3. Level 3: The Implementation Detail (per-component) Detailed design for each component: data models, API specifications, configuration, deployment procedures, and operational runbooks. This level serves the engineers who build and maintain each component. It lives close to the code — in the repository, not in a separate document system — because documentation that is separated from the code it describes drifts immediately.