What needs to be finished first
A list of the actual readers of the doc (architects, new team members, auditors, ops) with their information needs is available.
Important architecture decisions are documented as ADRs or are being captured in parallel so that chapter 9 (decisions) can link to them.
What needs to be ready before start
arc42 template (Markdown version of arc42/arc42-template on GitHub); diagram tool (PlantUML, Structurizr, draw.io); repo directory `docs/architecture/`; glossary file; links to the ADR directory and possibly C4 diagrams.
One main author, often an architect or tech lead, as owner; one to three reviewers from Engineering and Ops; optional stakeholder from Business for chapter 1 (goals).
Current system overview; list of external interfaces; known quality goals, ideally from a Quality Attribute Workshop; constraints (regulatory, technical, organizational); existing diagrams.
1-2 days initial, then 1-2 h maintenance per sprint
Clone the template repository and store it in `docs/architecture/` as a Markdown structure. Use separate files for chapters 1-12 or one combined file. Define a diagram inclusion convention, for example PlantUML in the repo, rendered during the build.
The one question this method answers
Which architecture decisions, structures, and quality attributes does the reader need in order to understand, operate, and evolve the system?
Marker: Sektion
| Step | Duration | Action | Hint |
|---|---|---|---|
1Chapter 1-2: Introduction, goals, constraints | 2-3 h | Describe the problem in 5-10 sentences. List three to five quality goals in prioritized order. Add a stakeholder table with information needs. Include constraints (technical, organizational, conventional). | Quality goals must be prioritized. Anyone who marks all quality attributes as important has no decision basis and the document becomes arbitrary. |
2Chapter 3-4: Context and solution strategy | 3-4 h | Document business context and technical context as a diagram plus table. Summarize the solution strategy (architecture approach, top-level decisions, frameworks) in 1-2 pages. | Chapter 4 is NOT detailed design, but the short answer to how the system is built. More than 2 pages is too much and belongs in chapter 5. |
3Chapter 5: Building block view | 3-5 h | Create a white-box view in 2-3 levels (C4 container, C4 component). For each block, add responsibility, interfaces, and fulfilled requirements. No code classes. | Not every block needs a white-box view. Only the ones with complexity or risk. Otherwise the document explodes and nobody keeps reading. |
4Chapter 6-7: Runtime view and deployment view | 3-4 h | Runtime: 3-5 important scenarios as sequence diagrams. Deployment: hardware or cloud topology with nodes, networks, and deployment units. | Choose scenarios that make architecture decisions visible (failover, scaling, critical paths). The happy-path sequence is secondary. |
5Chapter 8-9: Cross-cutting concerns and decisions | 2-3 h | Cross-cutting concepts (security, logging, error handling, persistence). Architecture decisions as a list with ADR links and a short rationale. | Make concepts concrete, not generic. 'Logging via ELK with trace ID correlation' is better than 'logging is important'. |
6Chapter 10-12: Quality, risks, glossary | 2-3 h | Quality scenarios, ideally from QAW, in a table. Technical risks and debt with owner and escalation status. Glossary with domain and tech terms. | Name risks openly. An arc42 doc without a risks chapter is marketing material, not an architecture document. |
What comes out at the end
Markdown directory under `docs/architecture/` with 12 chapter files, embedded diagrams (PlantUML or rendered SVG), links to ADRs, glossary, and test plans. Rendered in CI and deployable as HTML.
Docs are versioned in the same repo as the code. Changes go through pull requests with an architecture reviewer. Doc releases are tied to system releases (tag), so each code version has matching docs.
Compact working template for arc42 with context, input, output artifacts, and next step.
Pragmatic template for structured, living software architecture documentation.
When and for what do we use this method?
Which data, observations, decisions, or materials are available?
Short notes along the runsheet.
Owner, date, and success signal.
Concrete filled scenario, fictional example
Concrete filled scenario, fictional example
Processes orders from web and mobile, from intake through delivery to external carriers. Top 3 quality goals:
Event-driven via Kafka. 8 bounded contexts as microservices, languages Java 21 and Kotlin. Persistence: Postgres per service. Deployed on AWS EKS in eu-central-1 with multi-AZ.
Recognize symptoms and steer against them
All 12 chapters are filled, each more than 10 pages long. Nobody reads beyond the introduction.
Leave chapters out if they contain nothing substantial. Better 6 good chapters than 12 empty ones. Treat arc42 explicitly as opt-in per chapter.
PNG or JPG diagrams in the repo, without PlantUML or Structurizr source. Changes require the original tool.
Keep diagrams as text source (PlantUML, Mermaid, Structurizr DSL) in the repo and render them during the build. Otherwise images go stale quickly and are not updated.
Chapter 1 lists availability and performance as goals, without measurable definition.
Add one scenario per quality goal in chapter 10 with stimulus, response, and measure. Otherwise no evaluation is possible.
The arc42 doc was last changed 9 months ago, while the system has had 3 releases since then.
Make doc maintenance part of the definition of done. Add a doc update slot per sprint. For big releases, make a doc review an acceptance criterion.
The decisions chapter contains narrative paragraphs, but no links to ADRs.
Turn chapter 9 into a list with title and ADR link. The rationale lives in the ADR, not in arc42. Otherwise there are two competing truths.
Done signals checkable in under a minute
Go to the profile for purpose, similar methods, and sources or continue to the next method in the catalog.