Documentation That Engineers Actually Read

Subject: 90% of your documentation is waste

Hey there,

I audited documentation for a 40-person engineering team last month. They had 247 Confluence pages. I asked 5 engineers to find the deployment process. Three couldn't find it. One found an outdated version. One gave up and asked in Slack.

247 pages of documentation. Effectively zero useful documentation.

●This Week's Decision

The Situation: Your team has 200+ Confluence pages, wiki articles, or Google Docs. Half are outdated. New engineers ask the same questions in Slack that are theoretically answered in docs. Nobody trusts the documentation because they've been burned by stale information before.

The Insight: Most documentation is written because someone felt they should document something. That's the wrong motivation. Documentation survives only when an active force maintains it. Across every team I've advised, only four types of documentation have the natural maintenance pressure to stay current.

1. Architecture Decision Records (ADRs) ... 2-3 year half-life.

ADRs document why a decision was made, not what was decided. The code shows what. The ADR shows the context, options considered, and trade-offs accepted. They're stable because decisions don't change often ... and when they do, the new ADR supersedes the old one.

# ADR-007: Use PostgreSQL RLS for multi-tenancy

## Status: Accepted (2026-01-15)

## Context

We need tenant isolation for SOC2. Options: application-level
filtering, schema-per-tenant, row-level security.

## Decision

PostgreSQL RLS. Enforced at the database layer, impossible to
bypass in application code.

## Consequences

- Every query must set tenant context: SET app.current_tenant = $1
- 3-5% query overhead from RLS policy evaluation
- Cannot accidentally leak cross-tenant data

2. Runbooks ... maintained by 3 AM urgency.

When production is down at 3 AM, the on-call engineer updates the runbook with what actually worked. Urgency is the strongest documentation maintenance force. Runbooks that get used in incidents stay current. Runbooks for systems that never break become stale ... and that's fine.

3. Onboarding guides ... maintained by new hire feedback.

Every new engineer is a documentation tester. They follow the guide, hit gaps, and either fix them (docs-as-code) or report them. If new hires join quarterly, the guide gets tested quarterly. Build onboarding as a checklist with "update this doc if anything is wrong" as the final step.

4. API contracts ... generated from code.

OpenAPI specs generated from your route definitions. TypeScript types generated from your database schema. These stay current because they're derived from the source of truth ... the code itself. Manually written API docs diverge within weeks.

Everything else ... meeting notes, "how we do X" guides, process documentation, feature specs ... decays. Don't invest in documentation types that lack a maintenance mechanism.

The implementation rule: documentation lives in the code repository, not in a wiki. Docs-as-code means PRs include doc changes. CI validates links. Search works. Version history is git log.

When to Apply This:

• Teams with more than 5 engineers where knowledge sharing matters
• Organizations with 50+ wiki pages where search yields more stale results than current ones
• Any team where new engineers rely on Slack questions instead of documentation

●Worth Your Time

1. Cognitect: ADR Process ... Michael Nygard's original ADR proposal. Short, practical, and the format that's become an industry standard. The key insight: record the decision and its context, not the analysis that led to it.

2. Google: Documentation Guide ... Google's internal documentation philosophy: minimum viable documentation, maintained by ownership, tested by usage. Their distinction between "conceptual," "procedural," and "reference" docs clarifies what format serves which purpose.

3. Divio: Documentation System ... The four-quadrant framework: tutorials, how-to guides, reference, and explanation. Each serves a different reader need. The framework prevents "dump everything in one format" which is how most wikis become useless.

●Tool of the Week

Backstage ... Spotify's developer portal. Centralizes documentation, service catalog, and runbooks in one place with ownership tracking. Docs live alongside the services they describe, with visibility into which docs are stale. If your documentation problem is really a discoverability problem, Backstage solves it.

That's it for this week.

Hit reply if your team has a documentation problem they keep trying to solve with more documentation. I'll help you identify which docs to keep and which to delete. I read every response.

– Alex

P.S. For the complete engineering leadership framework ... from documentation to team scaling: Engineering Leadership: Founder to CTO.