Master this essential documentation concept
A document that captures an important technical or architectural decision made during software development, including the context, options considered, and reasoning behind the chosen approach.
A document that captures an important technical or architectural decision made during software development, including the context, options considered, and reasoning behind the chosen approach.
Many teams walk through architecture decisions in recorded design reviews, engineering all-hands, or async Loom updates — explaining the context, the options considered, and why a particular approach won out. In the moment, this feels thorough. Six months later, when a new engineer asks why the system is structured a certain way, that reasoning is buried somewhere in a video timestamp nobody can find.
This is where video-only approaches break down for architecture decision records specifically. An ADR is only useful if it's searchable, referenceable, and linkable from a pull request or onboarding doc. A 45-minute architecture review recording is none of those things. Your team ends up either re-explaining decisions repeatedly or making changes without understanding the original constraints that shaped them.
Converting recorded architecture discussions into structured documentation lets you extract the exact content an architecture decision record needs: the problem statement, the alternatives evaluated, and the rationale for the chosen direction. A recorded system design session, for example, can become a formal ADR that lives alongside your codebase — complete with the nuanced reasoning your architects actually voiced, not a sanitized summary written after the fact.
If your team regularly discusses technical direction on video but struggles to turn those conversations into durable records, see how video-to-documentation workflows can help →
A platform team switches from PostgreSQL to CockroachDB for global distribution, but six months later new engineers keep questioning why the non-standard database was chosen, reopening the same debates and slowing onboarding.
An ADR captures the evaluated alternatives (PostgreSQL with Citus, Amazon Aurora Global, CockroachDB), the constraints driving the decision (multi-region writes, CAP theorem trade-offs, operational cost), and the explicit rationale, giving new engineers a single authoritative source to read instead of interrogating senior engineers.
['Create ADR-0023-cockroachdb-adoption.md in the /docs/adr directory, filling in the context section with the specific scaling problem: 400ms write latency for EU users hitting a US-East PostgreSQL primary.', 'List each evaluated option with a pros/cons table covering consistency model, operational overhead, licensing cost, and team familiarity.', 'Record the final decision with explicit trade-offs acknowledged, such as accepting eventual consistency in partition scenarios in exchange for active-active multi-region writes.', 'Link the ADR from the database README, the infrastructure Terraform module, and the onboarding guide so it surfaces naturally during code review and setup.']
New engineers understand the database choice within their first week without requiring a 1-on-1 with the platform lead, and the team stops relitigating the decision in quarterly architecture reviews.
A product team ships a GraphQL API to replace REST endpoints, but partner developers and internal mobile teams keep filing tickets asking why REST was abandoned and whether REST will return, creating support overhead and eroding trust in the API roadmap.
An ADR documents the specific driver — partners needed to fetch nested order, customer, and inventory data in a single request, causing 7 sequential REST calls and 2.3s load times on mobile — and records that REST was kept for webhook callbacks where GraphQL offered no advantage.
['Write ADR-0041-graphql-partner-api.md capturing the quantified problem: average partner integration required 7 REST calls per page load, measured via API gateway logs.', 'Document three options evaluated: REST with compound documents (JSON:API), gRPC streaming, and GraphQL with persisted queries, including which partners were consulted during the evaluation.', 'State the decision boundary clearly — GraphQL for query/mutation operations, REST retained for webhooks and file upload endpoints — so future engineers know the scope.', 'Publish the ADR in the developer portal alongside the API reference so external partners can read the rationale without filing a support ticket.']
Partner support tickets asking 'why GraphQL' drop to near zero, and the mobile team confidently builds against the API knowing REST endpoints for webhooks are intentionally preserved and stable.
A frontend platform team migrates 12 separate npm packages into a Nx monorepo, but three months later two senior engineers propose splitting them back out, unaware of the specific CI/CD and versioning problems that originally drove the consolidation.
An ADR records the exact pain points that justified the monorepo — 45-minute cross-package integration cycles, inconsistent TypeScript config drift across repos, and inability to make atomic changes spanning the design system and consuming apps — making the original constraints visible before any reversal is attempted.
['Draft ADR-0007-nx-monorepo-frontend.md immediately after the migration decision, while the context is fresh, including the specific metrics: 45-min CI time, 12 repos with diverged ESLint configs, and 3 incidents caused by mismatched peer dependency versions.', "Document the alternatives evaluated: Turborepo, Lerna with independent versioning, and keeping separate repos with a private npm registry, with a scoring matrix against the team's criteria.", "Record dissenting opinions from engineers who preferred Turborepo, acknowledging their concerns about Nx's opinionated project graph, so future readers understand the decision was not unanimous.", 'Set a review date of 12 months in the ADR metadata so the team formally revisits whether the monorepo is still serving its purpose rather than drifting indefinitely.']
The proposal to split the monorepo is evaluated against documented original constraints rather than anecdote, and the team either validates the reversal with new evidence or confidently continues with Nx based on the recorded rationale.
A fintech team builds a compliance ledger using event sourcing, but auditors and new backend engineers repeatedly ask why the system stores events instead of current state, and compliance engineers spend hours in meetings explaining the architectural pattern rather than building features.
An ADR explains that regulatory requirements mandate a complete immutable history of every state change to customer accounts, that traditional CRUD with audit log tables was rejected because it allowed retroactive record deletion, and that event sourcing was selected specifically to satisfy SOC 2 Type II and PCI-DSS audit trail requirements.
['Write ADR-0015-event-sourcing-compliance-ledger.md with the regulatory constraint as the opening context: PCI-DSS Requirement 10.2 mandates tamper-evident logs of all access and changes to cardholder data.', 'Document the rejected CRUD-plus-audit-log approach with a concrete failure scenario: a database admin with DELETE privileges could remove both the record and its audit entry, which fails the tamper-evidence requirement.', 'Describe the event sourcing implementation chosen — Apache Kafka with log compaction disabled on the compliance topic, events stored in append-only S3 with Object Lock — linking to the infrastructure ADR for storage.', 'Attach a link to the external compliance requirement documents and the internal legal sign-off email so auditors can trace the decision back to its regulatory source.']
During the next SOC 2 audit, the compliance team shares the ADR directly with auditors as evidence of intentional design, reducing the audit preparation time by an estimated two days and eliminating recurring internal architecture explanation meetings.
ADRs written weeks after a decision is implemented lose the critical context of what alternatives were seriously considered and why they were ruled out. The moment of decision is when the trade-offs are most clearly understood by the team. Capturing the ADR as a pull request opened alongside the implementation PR ensures the reasoning is recorded before institutional memory fades.
An ADR that only describes the chosen solution provides no value over a README. The decision record becomes genuinely useful when it explains why plausible alternatives were not chosen, giving future engineers the information they need to know whether those alternatives are worth revisiting. Each rejected option should have at least one concrete, specific reason for rejection rather than a vague preference.
When a decision changes, editing the original ADR destroys the historical record of what the team believed and knew at a previous point in time. A new ADR that explicitly supersedes the old one preserves the full decision history, which is invaluable for understanding why a system evolved the way it did and for post-incident reviews. Both ADRs should link to each other bidirectionally.
ADR context sections written as opinions ('the team felt the current approach was too slow') become meaningless over time because opinions change and cannot be verified. Context anchored in measurable constraints ('p99 API latency was 1.8s under 500 concurrent users, exceeding our 500ms SLA') gives future engineers objective criteria to evaluate whether the original problem still exists. Quantified constraints also make it clear when a decision should be revisited.
ADRs stored in a separate wiki or shared drive become disconnected from the codebase they describe, making them invisible during code review and difficult to find when debugging a system. Storing ADRs as Markdown files in a /docs/adr directory within the repository ensures they are versioned alongside the code, appear in git blame and log history, and can be referenced in pull requests and commit messages. Engineers encounter them naturally rather than needing to know where to look.
Join thousands of teams creating outstanding documentation
Start Free Trial