Documentation for Software Architects
Documentation for architects is writing down decisions and structure so others can understand and challenge them. Architecture decision records capture a choice with its context and consequences, C4 diagrams show a system at four zoom levels, and design docs describe a proposed change before it is built.
Stage: Communication and Practice · Part of the Software Architect roadmap · Last reviewed 19 November 2026
What to learn in Documentation
- Write an ADR with context, decision, status and consequences
- Draw C4 context and container diagrams for a system
- Structure a design doc with goals, non-goals and alternatives
- Keep diagrams and docs in the repository beside the code
- Tailor a document to executives or engineers
- Mark a decision superseded instead of deleting history
Documentation interview questions
What is an architecture decision record?
An ADR is a short document capturing one significant decision, the context that led to it, alternatives considered and the consequences. Stored with the code, it explains why a system looks as it does when the original team has moved on.
What are the four levels of the C4 model?
They are context, showing the system and its users and neighbours, containers, the deployable applications and data stores, components inside a container, and code, such as classes. Most teams draw only the first two or three levels.
Where Documentation fits in the Software Architect roadmap
Documentation belongs to the Communication and Practice stage (advanced level), which takes about 5 hours. Lead the work.
Other units in this stage
Back to the full Software Architect roadmap