Documenting Decisions Before They’re Forgotten

Architecture decision records (ADRs) are a lightweight way to capture not just what was decided in a codebase, but why. At GitHub’s mobile team, ADRs now cover decisions affecting both the iOS and Android codebases individually, as well as cross-platform choices. The practice has grown in popularity since around 2017, particularly in long-lived, evolutionary codebases common in enterprise settings.

The value of an ADR isn’t in the act of writing it down; it’s in having that context available months later, when the original reasoning has faded.

Context for Your Future Self

An ADR is written at the moment the decision is made, not after the fact as a retrospective exercise. It distills the meetings, Slack threads, whiteboard sessions, and proof-of-concept experiments into a coherent record of the reasoning that led to a particular architectural choice.

Six to twelve months out, when you’re revisiting that architecture, the ADR restores the mindset you had when you built it. And when someone git blames you asking how the GitHubAPIClient module works, you can point them to the ADR instead of scheduling a half-hour pairing session to explain it from memory.

A Shared Understanding for Your Peers

ADRs force you to go beyond a pull request title like “this ships the feature for #3128.” They provide the longer-form explanation of why the system is built one way and not another—typically captured in sections like “Alternatives Considered” and “Pros/Cons.”

What feels obvious to you may be opaque to a teammate. Writing down your thought process gives them a window into your reasoning and supports what’s sometimes called “decision socialization”: the team arrives at a decision together and feels collective ownership over maintaining it, rather than inheriting decisions made in isolation.

Written before you open a pull request, an ADR also improves the review itself. Reviewers come in already understanding how a change to a file like APIClient+Caching.swift fits into the broader data-fetching architecture, so the review focuses on the diff rather than a re-explanation of the system.

Asynchronous Onboarding for Future Teammates

As teams grow, communication channels multiply. A three-person team has three pairwise lines of communication; a four-person team has six. Scale to a full engineering organization with designers, product managers, and engineering managers, and the coordination cost becomes prohibitive.

ADRs let you communicate architectural reasoning asynchronously. New teammates can read through the records to understand how and why the codebase evolved, without needing a Zoom call for every major decision. Documenting decisions in writing removes the per-person, per-decision onboarding overhead.

In the best case, the practice is self-reinforcing: new teammates eventually write their own ADRs that supersede yours, and you get to learn from them in return.

Further Reading