Building a Culture of Documentation That Doesn't Die

Why Documentation Initiatives Fail

Every engineering team has launched a documentation initiative. Most of them are dead within six months.

The pattern is always the same. A driven engineer or manager declares "we need better docs." A tool is chosen: Notion, Confluence, a wiki, a docs-as-code repo. Everyone agrees docs are important. For three weeks, docs get written.

Then a crunch happens. Docs fall behind. They're wrong. Nobody updates them because they're already wrong, so nobody reads them. So nobody updates them.

The problem was never the tool. The problem is that documentation was treated as a task, not a practice.

The Fundamental Insight

Documentation dies because it's treated as something you do after the work, not during it.

When documentation is a separate activity ("we should write this up later"), it competes with everything else on the backlog and loses. Every time.

When documentation is built into how work happens, it gets written because not writing it makes the work harder.

That's the shift. Documentation as a byproduct of thinking, not as a chore after shipping.

The Types of Documentation Worth Writing

Not all documentation is equal. Some types have high return; others are maintenance traps.

High value, write more:

Decision records (ADRs): a short doc capturing why a technical decision was made, what alternatives were considered, and what tradeoffs were accepted. These age well and are invaluable when the original author is gone.

Runbooks: step-by-step procedures for specific operational scenarios. "How to roll back a bad deploy." "How to restore from backup." Written once, saves hours under pressure.

Onboarding guides: the document you wish existed when you joined. Written by the person who just joined, while their perspective is fresh.

Lower value, write less:

Architecture overviews: valuable, but go stale fast. Link to the code instead of duplicating it.

How-to tutorials for internal tools: only if the tool is stable. If it changes every month, the tutorial becomes misinformation.

The Practices That Actually Work

Write docs in the same PR as the code. When a new feature ships, the PR includes a short doc update. Review the doc alongside the code. This creates a cultural norm: code without docs isn't done.

The definition of done includes docs. Add "documentation updated or created" to your team's definition of done for tickets. It sounds bureaucratic, but it reframes documentation as completion, not overhead.

New engineers own onboarding docs. When someone joins, give them a mission: improve the onboarding guide as you go through it. They document the gaps while the gaps are fresh. The guide is always written by someone who just needed it.

Rotation of the doc reviewer role. Periodically, someone on the team owns "doc quality" for a sprint. They find outdated pages, file issues, update stale content. Not a permanent role, but a rotation that distributes responsibility.

Archive aggressively. An outdated doc is worse than no doc. It provides false confidence and wrong answers. Mark docs with a "last verified" date. Delete or archive anything older than six months that nobody has maintained.

The Repo Beats the Wiki

For most engineering teams, documentation lives best in a Git repository alongside the code.

Why:

• Docs are reviewed in PRs like code
• Changes are tracked and attributed
• Docs live close to what they describe
• Outdated docs become visible in the same diff that changed the behavior

The workflow:

docs/
  adr/
    0001-use-postgres-not-mysql.md
    0002-adopt-opentelemetry.md
  runbooks/
    rollback-procedure.md
    database-restore.md
  onboarding/
    first-week.md
    dev-environment-setup.md

A CONTRIBUTING.md that explains where docs live and how to update them closes the loop.

What to Measure

Two metrics worth tracking:

Docs coverage of incidents: for the last five incidents, how many had runbooks? If the answer is two out of five, write the missing three.

Onboarding feedback: ask every new joiner at the 30-day mark: what was missing from the docs? Quantify the gap over time.

You don't need a comprehensive doc health dashboard. You need two numbers trending in the right direction.

The Real Goal

The goal isn't complete documentation. It's a team where people's first instinct is to write things down, not because they're required to, but because they've seen it save themselves and their teammates enough times to believe in it.

That takes time. But it starts with the next PR.