The Day We Trashed Our Design Wiki for ADRs and Reclaimed Our Engineering Velocity

I was staring at a Slack thread that had reached 47 replies, all debating why we had chosen DynamoDB over Postgres for the payments microservice three years ago. The lead engineer who made the call had left the company in 2024, and our internal wiki page on the subject was a digital ghost town, last edited by "Anonymous Guest" and featuring a broken diagram link. We were paralyzed by "architectural archaeology," spending more time guessing at past intents than building new features.

That afternoon, I deleted the bookmark to our "Architecture" wiki folder. We weren't going back.

The Problem with "Wiki Rot"

The fundamental issue with external documentation—Confluence, Notion, Google Docs—is that it exists in a different dimension than the code. When you’re in the flow, deep in a refactor, you aren’t checking a browser tab to see if your changes align with a decision made during a 2022 offsite.

Wikis are where technical context goes to die. They suffer from:

1. Low Discoverability: If it’s not in the repo, it doesn’t exist.
2. Lack of Versioning: You can see the _current_ state of a wiki, but seeing the _evolution_ of a decision is a nightmare of "Page History" clicks.
3. Zero Enforcement: You can merge a PR that completely contradicts a wiki doc without a single warning.

Enter the ADR (Architecture Decision Record)

We decided to move our decision-making process into the one place developers actually look: the Git repository. We adopted the Architecture Decision Record (ADR) format.

An ADR is a short text file (Markdown) that captures a specific choice, the context around it, and the consequences it brings. We keep them in a docs/adr folder at the root of each service.

Here is what a real ADR looks like in our payments repo:

# 0004. Use Idempotency Keys for Stripe Integration

Date: 2025-11-12
Status: Accepted
Deciders: @jdoe, @asmith, @cto_dave

## Context and Problem Statement

We are seeing occasional 504 Gateway Timeouts when calling Stripe's Charge API.
Because our retry logic is aggressive, we risk double-charging customers if
the initial request actually succeeded on Stripe's end but timed out on ours.

## Decision Outcome

Chosen option: "Custom Idempotency-Key Header", because it is natively
supported by Stripe and allows us to safely retry requests for up to 24 hours.

### Implementation Notes

- Use the `internal_transaction_id` as the key.
- Keys must be stored in the `outbox` table before the API call is made.

## Consequences

- Good: Eliminated double-charging edge cases.
- Bad: Increased database write overhead (one extra row per transaction).
- Neutral: Developers must now ensure transaction IDs are generated upstream.

The "Git-Flow" of Decisions

The magic isn't in the Markdown file itself; it’s in the Pull Request.

By moving decisions into Git, the "Why" becomes part of the code review. If I want to change our caching strategy, I don't just send a Slack message. I submit a PR that creates 0012-move-to-redis-cluster.md.

The team reviews the _logic_ before they ever see the _code_. This shifts the "architectural heavy lifting" left. We find flaws in the reasoning before someone spends a week writing the implementation. When the PR merges, the documentation and the feature arrive in the main branch at the exact same millisecond.

Dealing with the "Superseded" Problem

One of the biggest wins is handling change. In a wiki, you just edit the text, and the old context vanishes. With ADRs, you never delete. If a decision changes, you create a new ADR and mark the old one as Superseded.

# Example directory structure
docs/adr/
  0001-record-architecture-decisions.md
  0002-use-mongodb.md (Status: Superseded by 0005)
  0003-auth0-integration.md
  0004-use-idempotency-keys.md
  0005-migrate-to-postgres.md (Status: Accepted)

This creates a paper trail. When a new hire asks, "Why on earth did we use Mongo for six months?", I don't have to remember. I just tell them to read ADR 0002 and 0005. The pain, the lessons learned, and the eventual migration are all right there.

The Payoff: Engineering Velocity

Since trashing the wiki, our "time-to-context" has plummeted.

When a developer joins a project, they read the docs/adr folder. In thirty minutes, they understand the three-year history of the system's soul. They see the trade-offs we were forced to make during the 2025 traffic spike and why we chose a specific library over another.

We stopped having the same arguments every six months because the "Why" is immutable. If you want to challenge a decision, you have to read the ADR, understand the context we were in, and provide a new ADR that explains why that context no longer applies.

Velocity isn't just about how fast you type; it's about how few times you have to stop to ask for directions. By putting our decisions in Git, we stopped guessing and started shipping.