The goal of documentation is that the system doesn’t depend on specific people to be understood. Too much documentation goes stale and nobody reads it; too little, and knowledge leaves with whoever leaves the team. Three practices cover most cases.
C4 model: diagrams in levels
Created by Simon Brown, it organizes diagrams like a map with zoom: each level shows more detail to a different audience.
| Level | Shows | For whom |
|---|---|---|
| Context | The system as a box, users and external systems | Everyone, including business |
| Containers | Applications, services and databases, and how they communicate | Tech team, operations |
| Components | The main parts inside a container | Developers |
| Code | Classes and relationships | Rarely worth drawing; the code already is that |
In most projects, the first two levels are enough.
ADR: decision records
An Architecture Decision Record is a short text, one per important decision, kept in the repository:
# 7. Use PostgreSQL as the main database
Status: accepted (2026-03-10)
Context: we need transactions and flexible queries; the team already knows SQL.Decision: managed PostgreSQL in the cloud.Consequences: we give up simple horizontal scaling; revisit above 5 TB.The value is in the context: two years from now, nobody remembers why the decision was made. ADRs are not edited; a new decision supersedes the old one.
Documentation next to the code
- A README with how to run, test and release.
- Diagrams as code (Mermaid, Structurizr), versioned and reviewed in the same pull request that changes the system.
- API contracts generated from the code (OpenAPI).
See also: Software architecture fundamentals.
- To dig deeper: c4model.com and Unraveling system architecture with the C4 model (in Portuguese)