When you see it...
From smaller teams to larger ones, from the senior SWE managing the entire backlog to EOs, POs, and SMs juggling overlapping responsibilities, I have often found myself in meetings or PR discussions nitpicking scope details and suddenly realizing one of two things:
- I disagree with the broader implementation picture.
- I do not even remember whether I agreed with it in the first place.
That second one is worse.
Half-measures (Best-case scenario)
"Uhh, there is a Confluence page about this decision. We had a meeting for that."
Clicks the link.
Scans a page with 10 comments (8 resolved, 2 still open).
OK, this makes a bit more sense now.
Still, I do not remember what we said. I do not remember how long it took, and it probably took longer than it should have.
Even in this best-case scenario, I am still left with two problems:
- I do not remember the back-and-forth, and some of it was probably important.
- If I now have a different opinion, I really do not want to reopen the topic. That usually means more meetings, more pages, and more comments. Atlassian may be doing a great job with version control, but I do not want to be stuck restoring version 23 of a Confluence page that nobody will care about two weeks later.
Give credit where it is due
That does not mean Confluence is useless.
Architects, PMs, and business stakeholders need version control, comments, and discussions too. You cannot expect a product owner:
- To log in to GitHub every time they want to sync with the architect on whether the team is migrating the DB.
- To align on the confidence level of PI objectives with different POs inside a pull request.
Confluence has its place.
But at the same time, nobody wants to spend all of this just to discuss something like a new or existing PR label:
- 10 minutes to raise it during the daily stand-up
- 5 minutes to schedule a call
- 20 minutes to prepare a page explaining the current state and the proposal
- 35 minutes for the meeting itself
- 20 minutes for the notes afterward
- 20 minutes updating the page with the latest comments and decisions
And yes, those numbers are completely realistic.
Architecture Decision Records
This is where ADRs help.
An ADR is a lightweight record of an important technical decision: why it was needed, what options were considered, what was chosen, and what tradeoffs came with that choice.
At its simplest, it is just a markdown file living in your repo, somewhere like this:
docs/
adrs/
0001-use-topic-a.md
That is basically it.
A small document, committed with the code, with sections such as:
- Context: what problem are we trying to solve?
- Decision: what did we choose?
- Alternatives considered: what were the other realistic options?
- Consequences: what do we gain, and what do we give up?
- Status: proposed, accepted, superseded, deprecated
Nothing fancy. Just enough to preserve the reasoning behind a technical decision close to the codebase where engineers will actually look for it.
Basic rules
Keep ADRs for technical topics that are likely to be searched while someone is working in the repo. If you used a specific pattern, tool, or extension, I would much rather
Ctrl+Fthe repo and find the reasoning in the docs than dig through a GitHub page or old meeting notes.Make the person opening the PR the driver of the discussion. They should gather feedback, collect comments, help the team converge on a decision, and eventually merge or close the PR with the ADR alongside the change.
Do not optimize for unanimous agreement. Optimize for a clear decision with explicit tradeoffs and enough context that the next person can understand why it happened.
That is the real value: not perfect documentation, but recorded reasoning close to the codebase.
If you want a good collection of ADR templates, look here.
PS1: Use this as a starting point for introducing ADRs to your team.
PS2: An agent helped with syntax refactoring. The expressions, the main writing, the flow and the pain is mine :)
Top comments (0)