Architecture documentation works best when each fact has one clear job and one authoritative home. Use a setup guide for repeatable development tasks, a system map for the architecture as it exists now, and an architecture decision record (ADR) for why the team accepted a significant design choice. Keep an operational runbook for responding to production conditions. Link the records so a reader can move between them without treating one as a substitute for another.
Direct answer: A setup guide answers “How do I run or change this?” A system map answers “What is connected, and how does it work now?” An ADR answers “Why did we choose this, and what follows from that choice?” A runbook answers “What should an operator do when this condition occurs?” Assign an owner and a change trigger to each, then link the records.
Choose a record by the question it must answer
| Reader’s question | Record to maintain | What makes it trustworthy |
|---|---|---|
| How do I build, run, test, or release this service? | Setup guide | A teammate can follow the steps in the stated environment |
| Which systems and services communicate today? | System map | Its scope, boundaries, relationships, and current version are clear |
| Why did we choose this architecture? | ADR or decision log | The decision’s context, status, rationale, and consequences are preserved |
| What should on-call do during a known failure? | Runbook | An operator can follow and verify the procedure with the required access |
This is a practical split for architecture work, not a universal taxonomy or a requirement to create four separate files. Diátaxis distinguishes tutorials, how-to guides, reference, and explanation by the user need each serves. arc42 offers a broader, adaptable architecture-documentation template with sections for context, structure, runtime, deployment, decisions, quality requirements, risks, and more. Use the structure that fits the system and its stakeholders; the key is to stop one paragraph or diagram from silently claiming several kinds of authority.
Setup guide: instructions a teammate can execute
A setup guide contains prerequisites, local configuration, commands, test steps, and common setup failures. It is task-focused: tell a competent contributor how to get a specific job done, then link to deeper explanation or reference material where needed. Diátaxis describes this as a how-to guide rather than a tutorial, reference page, or general explanation.
Put the guide wherever contributors will find and maintain it reliably. For code-specific steps, a README or versioned documentation beside the repository is often practical because changes can be reviewed with the code. State the supported runtime, required services, and any environment-specific assumptions. A command that works only on one author’s machine is not a tested setup instruction.
Check the guide by asking someone other than its author to start from the stated prerequisites and complete the task. If the steps require hidden context, add that context or link to its real source. Update the guide when a supported command, dependency, configuration requirement, test workflow, or release step changes—not whenever an unrelated implementation detail changes.
System map: a scoped view of the present
A system map describes current boundaries, important building blocks, external dependencies, and relationships. Start with the view that answers an actual reader’s question. The C4 model’s system-context and container diagrams are useful starting points; C4 says most teams do not need all four levels, and recommends adding lower-level views only when they provide value. A service interaction, deployment, or data-flow diagram can be added when the system context or container view cannot answer the question.
A map should state its scope and level of detail. Give the diagram a descriptive title, explain important notation, name its elements, and label relationships with their direction and meaning. The C4 diagram review checklist provides concrete checks for scope, element types, legends, and relationship labels. For large systems, C4 recommends splitting a crowded model into focused diagrams with distinct scopes rather than trying to fit every component into one.
A map changes when the represented architecture changes: a service boundary moves, a dependency is introduced or removed, ownership changes, or a critical flow is redirected. Update it with that change, and keep a review date as a backstop rather than as a substitute for checking against the system. Do not copy details that already have a better-maintained source of truth, such as API schemas, infrastructure configuration, or a service catalog; link to them instead.
For a method of deciding how much to include in a lean documentation set, see minimum viable architecture documentation. To make a diagram reviewable, use the architecture diagram definition of done.
ADR: preserve the reason for a consequential choice
Use an ADR when a choice has lasting consequences for system structure, quality attributes, dependencies, interfaces, or construction techniques. Not every code change needs an ADR. arc42 recommends recording important decisions with their motivation, and AWS describes an ADR as a record of a significant architectural choice, its context, and consequences.
A useful ADR names the decision and records:
- Context: the problem, constraints, stakeholders, and forces that mattered.
- Options and criteria: the alternatives the team considered and how it evaluated them.
- Decision and status: what the team chose, and whether the record is proposed, accepted, rejected, or superseded.
- Consequences: benefits, costs, risks, and follow-up work, including negative consequences.
- Links: the affected map, contract, implementation change, and any decision that this one replaces.
An ADR is a historical record, not the current architecture map. Under the AWS ADR process, an ADR may be revised while it is proposed; once accepted or rejected, it is immutable. If a later decision changes the direction, propose a new ADR. Once the replacement is accepted, mark the earlier record as superseded. Update the current map separately so readers can see the system that exists now.
Runbook: procedures for operating the system
A runbook describes how to respond to a known operational condition: for example, how to inspect a queue backlog, decide whether to pause a consumer, and verify recovery. It is not the same as a setup guide. Setup instructions help a contributor prepare a development environment; a runbook helps an operator act under a production condition.
Keep operational steps near the monitoring, incident, and access context needed to use them. State the trigger, required permissions, safe checks, action, expected result, escalation path, and rollback or stop condition. Test the procedure in a representative exercise or safe environment. Link the runbook to the system map for orientation, but keep actionable commands in the operational record so they can be reviewed and corrected there.
Example: one architecture change, four records
Consider a service that moves invoice processing from a synchronous request to a queue. The diagram below is only an example; it does not describe Arialine or a real customer system.
flowchart LR
client["Billing client"] -->|"submits invoice request"| api["Billing API"]
api -->|"enqueue invoice"| queue[("Invoice queue")]
queue -->|"delivers invoice job"| worker["Invoice worker"]
worker -->|"stores processing result"| store[("Invoice store")]
worker -->|"sends receipt request"| mail["Email provider"]
The records answer different questions:
| Record | What to change |
|---|---|
| Setup guide | Explain how to start the API and worker locally, configure the queue emulator, and run the relevant tests |
| System map | Show the API, queue, worker, data store, and external provider as they exist after the change |
| ADR | Record why the team chose queued processing, the alternatives and constraints it considered, and the consequences such as asynchronous completion |
| Runbook | Explain how to diagnose a growing queue, identify a stuck consumer, and verify that processing has recovered |
Link the exact map version and implementation change from the ADR. A link to a mutable “latest diagram” alone may later point at a state the decision did not create. The guide and runbook should link to the current map, but should not copy its full architecture description.
Decide whether to split the files
Separate records when they have different owners, audiences, update triggers, or review rules. Keep them together when the document remains easy to navigate and each section clearly identifies its authority and status. Logical separation matters more than the number of files.
A simple ownership model is:
- The service or repository maintainer owns setup steps.
- The service or area owner is accountable for the current map.
- The ADR author coordinates the decision record; the relevant team reviews it.
- The operational owner maintains and exercises the runbook.
Avoid making one named person the only path to correction. Name a team or role that can review updates, and point readers to the source they should change. When documents live in different systems, use stable links and show version, commit, or date when the relationship could otherwise become ambiguous.
Use a change review to keep the records aligned
When a change affects architecture, ask these questions during design or code review:
- Does it change a system boundary, dependency, data flow, deployment, or operational responsibility? Update the affected system map.
- Does it make a consequential choice among alternatives? Write or update a proposed ADR before acceptance; preserve the accepted or rejected record afterward.
- Does it change how a contributor builds, tests, or releases the service? Verify the setup guide from its stated starting conditions.
- Does it change how an operator detects or responds to a failure? Update and exercise the runbook.
- Do the links point to the current map and to the exact historical decision or version they refer to?
This is a more useful freshness check than changing every document on a calendar. Architecture diagrams drift when changes and reviews lose their source context; an explicit owner, change trigger, and review path make that mismatch easier to catch. For a deeper update cadence and review-trigger approach, see how often to update architecture diagrams.
Where Arialine fits
When architecture is discussed in Slack, Arialine can keep a Mermaid system map on a stable board message with version history, source, and change provenance that can point back to the Slack messages that requested revisions. The stored history is authoritative for board versions. Its separate decision-ledger display is an updatable mirror: it appears as a standalone Canvas where Slack permits, or as a message in the board thread on Slack Free (Arialine decision-ledger documentation). For the related diagram-history pattern, see decision ledgers for architecture diagrams.
Keep setup instructions, API contracts, runbooks and ADRs with their existing owners and link them to the map. If that workflow is relevant, reviewing and revising diagrams in Slack explains the Slack-specific path.
FAQ
Is an architecture diagram a setup guide?
No. A diagram can show components and relationships, but it rarely provides the ordered prerequisites and commands needed to build or test a service. Link the diagram from the guide rather than duplicating those steps.
Does an ADR show the current architecture?
No. An ADR explains a decision and preserves why it was made. The current map describes the system as it exists now. Link an ADR to the relevant map version, then update the map when the implementation changes.
Do these records need to be separate files?
No. Separate them when their owners, audiences, update triggers, or authority differ. A single documentation site can host all of them if each record is clearly scoped and changes are reviewed under the right rules.
Can a proposed ADR be edited?
Yes. A proposed ADR can be revised during review. Under the AWS process, it becomes immutable once accepted or rejected; a later change is captured in a new ADR that supersedes the earlier decision when accepted.
Where do API references belong?
Keep API contracts in the specification or reference source that owns them, such as an OpenAPI description for an HTTP API. Link from the map or ADR instead of copying the contract into a diagram description that can drift.
Add to my Slack