DEV Community

Cover image for Why did we choose this again?" - How ADRs Solved Our Documentation Problem
Yuto Takashi
Yuto Takashi

Posted on

Why did we choose this again?" - How ADRs Solved Our Documentation Problem

#architecture #documentation #productivity #softwareengineering

Why You Should Care

Ever had a new team member ask "why are we using this tool?" and you couldn't remember the exact reason? Or worse, spent hours digging through Slack threads and meeting notes trying to reconstruct a decision from 6 months ago?

That was me until I discovered Architecture Decision Records (ADRs).

The Problem: Scattered Information

I recently wrote about evaluating project management tools for our 30-person team. We had:

  • Redmine (database maintenance nightmare)
  • Azure DevOps (too complex, nobody used half the features)
  • Discussions scattered across Slack, Google Docs, and email

Someone commented: "You should write an ADR for this."

My reaction? "What's an ADR?"

What is an ADR?

Architecture Decision Record = A short document that captures why you made a technical decision.

That's it. Simple format:

# 001. Evaluate Linear for Project Management

## Status
Proposed (evaluating)

## Context
- 30-person team, tools fragmented
- Redmine: maintenance issues
- Azure DevOps: too complex, underutilized

## Decision
Evaluate Linear as unified solution
- Simple UI (learned from Azure DevOps)
- Cost: ~$3,000/year vs $12,000 Redmine maintenance
- Cross-team visibility

## Consequences
Pros: Simple, cheaper, unified
Cons: English UI, less customization
Unknown: Actual usage experience
Enter fullscreen mode Exit fullscreen mode

ADR vs Meeting Notes

Meeting notes capture what happened:

2:00 PM - Alice: I think Linear is good
2:05 PM - Bob: But it's in English
2:10 PM - Carol: What about Jira?
...
Enter fullscreen mode Exit fullscreen mode

ADR captures the decision:

## Decision: Linear

## Why
- Simple (avoiding Azure DevOps mistake)
- Cost effective
- Cross-team visibility

## Alternatives Rejected
- Jira: expensive, complex
- GitHub Projects: weak reporting
Enter fullscreen mode Exit fullscreen mode

Six months later, which one helps your future self more?

Keeping ADRs Alive (The Real Challenge)

The biggest risk? ADRs becoming dead documentation.

Here's what works:

1. Keep It Simple (5-10 minutes max)

If it takes an hour to write, you're doing it wrong.

# 003. Use Linear

## Context
Tools fragmented, need unification

## Decision
Linear - simple, affordable

## Consequences
Good: unified, cheap
Bad: English UI, less customization

Details: [Meeting notes](link)
Enter fullscreen mode Exit fullscreen mode

2. Make Them Useful

  • Onboarding: New members read them
  • Questions arise: "Why this?" → "Check ADR-003"
  • Quarterly review: Update or deprecate

3. Living Documents 

## Status
Accepted (2026-01-22)

## Update (2026-04-15)
After 3 months:
- English UI was fine
- BUT: needed spreadsheet alongside
  due to limited custom fields
Enter fullscreen mode Exit fullscreen mode

4. Don't Force It

Culture comes from convenience, not mandates.

Start with one ADR. Share it. If someone says "this is helpful," you've won.

The Perfection Trap

"But what if I miss important information?"

You don't need 100% completeness.

Your future teammates need:

  1. What you chose
  2. Why you chose it
  3. What else you considered
  4. Main trade-offs

That's 80% of questions answered.

The other 20%? Link to meeting notes.

Comparison 

Perfectionist approach:
- Time: 3 hours
- Completeness: 100%
- Written: 1-2x per year
→ Result: Most decisions undocumented

Pragmatic approach:
- Time: 5-10 minutes
- Completeness: 70-80%
- Written: 2-3x per month
→ Result: Most decisions documented
Enter fullscreen mode Exit fullscreen mode

70% information beats 0% information.

Example: Google's Design Docs

Google has a similar practice called "Design Docs":

"A design doc is not a spec. It doesn't need to be perfect. It's a tool for discussion."

Their approach:

  • Not required, but encouraged
  • Bullet points are fine
  • Start discussion before coding
  • Review and improve together

My Takeaway

When I wrote that project management tool article, I was already doing ADR-style thinking:

  • Problem context ✓
  • Options considered ✓
  • Trade-offs ✓
  • Current decision ✓

I just didn't know the term.

ADRs are letters to your future self and team.

They answer: "Why did we do this?" when everyone has forgotten, moved on, or left the company.

Getting Started

  1. Try one ADR for your next technical decision
  2. Keep it short (5-10 minutes)
  3. Store in Git (docs/adr/0001-your-decision.md)
  4. Share with team and see if they find it useful
  5. Iterate based on feedback

That's it. No fancy tools needed. Just markdown files in your repo.

Resources

Update: We actually implemented this at my company. Started with one ADR. Now it's standard practice. The trick? Don't mandate it—let the value speak for itself.

What's your experience with decision documentation? How do you handle "why did we choose this?" questions? Drop a comment below! 👇

I write more about decision-making and reflective practices for engineers.
If you're interested, you can find more here: https://tielec.blog/

Top comments (0)