Documentation That Developers Actually Write and Read
Apply developer documentation best practices with ADRs, comments and tested examples. Use the WRITE system to keep changes reviewable and find stale guidance.
I've watched three different teams spend weeks building beautiful documentation sites. Confluence spaces with custom templates. Notion databases with ownership tags. GitBook deployments with search and versioning. Six months later, every one of those systems was a graveyard. Pages last updated in Q1. Broken links everywhere. New engineers ignoring the docs entirely because they learned on day two that the docs were lies.
The problem isn't that developers are lazy. The problem is that most documentation strategies are designed by people who think documentation is a content problem. It's not. It's an incentive problem and a proximity problem. I've found exactly one approach that works long-term, and it looks nothing like what most teams attempt.
# The Contrarian Take: Most Documentation Should Not Exist
Here's what I believe after 8 years of trying everything: 80% of the documentation teams write should never have been created. It was outdated before the ink dried because the code it described was still changing. It created a false sense of understanding that was worse than no docs at all.
I ran an experiment across two teams. I instrumented our documentation with analytics: page views, time on page, and search queries. Here's what I found after 90 days:
Documentation Type
Views/Month
Avg Time on Page
Updated Regularly
API reference (auto-generated)
342
45 seconds
Yes (automated)
Architecture Decision Records
128
3.2 minutes
Yes (append-only)
Inline code comments (why-focused)
N/A (in IDE)
N/A
Yes (code review enforced)
Onboarding guide
23
8.1 minutes
No (stale after 2 months)
Module README files
89
1.4 minutes
Sometimes
Confluence design docs
12
32 seconds
No (abandoned)
Runbooks
67
5.7 minutes
Only after incidents
In this account, the more-used documents were generated references, decision records and material close to the code. Generation does not establish accuracy, and ADR status still needs maintenance when a decision is superseded. Usage in these two teams does not establish what every developer reads.
ADRs are the single highest-ROI documentation practice I've found. They record why a decision was made, what alternatives were considered, and what tradeoffs were accepted. The ADR guide gives the format and review process.
markdown
# ADR-012: Use Event Sourcing for Payment State## StatusAccepted (2026-01-15)## ContextPayment state was stored as mutable rows. We had 3 incidents in Q4where state corruption caused double-charges. Debugging requiredreconstructing state from logs manually.## DecisionPayment state transitions use event sourcing. Current state isderived from replaying events. Events are immutable and append-only.## Consequences- Slower reads (must replay events or maintain projections)- Storage cost increase (~40% more for payments table)- Complete audit trail eliminates the double-charge class of bugs- Team needs training on event sourcing patterns## Alternatives Considered- State machine with audit log: simpler but doesn't give us replay- Soft deletes with versioning: doesn't capture intent of transitions
Preserve the accepted ADR as a historical record. If the decision changes, write a new ADR and update the old record's status and replacement link. Readers still need a clear route to the current decision.[2]
I keep ADRs in docs/adr/ in the repo, not in Confluence. They're versioned with the code. They show up in code search. They're reviewed in PRs.
Not comments that explain what code does. Comments that explain why the code does something non-obvious.
typescript
// BAD: explains what (the code already says this)// Iterate through users and filter by active statusconst activeUsers = users.filter(u => u.isActive);// GOOD: explains why (context that isn't in the code)// We filter before the DB query instead of using a WHERE clause// because the isActive flag depends on a 30-day rolling window// that's computed client-side. See ADR-008 for why we didn't// move this to a database computed column.const activeUsers = users.filter(u => u.isActive);
A "why" comment stays near the code it describes. When the code changes, the comment is right there in the diff. Reviewers will catch stale comments. A wiki page 3 clicks away? Nobody checks that.
Documentation with specific examples or references checked by CI. A configured check fails when it detects an error in the material it covers. Architecture fitness functions can test related structural decisions.[3]
typescript
// API documentation that's tested/** * @example * const result = await processPayment({ amount: 1000, currency: "USD" }); * // Returns: { id: "pay_xxx", status: "captured", amount: 1000 } */export async function processPayment(input: PaymentInput): Promise<PaymentResult> { // ...}// In your test suite:// Extract @example blocks and run them as tests// If the example doesn't match runtime behavior, the test fails
Other forms of executable docs:
OpenAPI specs generated from code annotations, validated in CI
Database schema docs generated from Prisma/TypeORM models
Dependency graphs auto-generated and committed to the repo
I've developed a rule I call the Proximity Principle: documentation accuracy is inversely proportional to its distance from the code it describes.
Distance from code Accuracy after 6 months
────────────────── ───────────────────────
Inline comments ~85% accurate
Same-repo README ~60% accurate
Same-repo docs/ ~45% accurate
Wiki (linked from ~20% accurate
repo)
Wiki (not linked) ~5% accurate
This isn't about discipline. It's about friction. Updating an inline comment takes 2 seconds during a code change. Updating a wiki page takes context switching to a browser, finding the right page, editing, and saving. That friction compounds across hundreds of changes until everyone gives up.
Figure 2. Tie documentation maintenance to the development workflow.
Here's the process I use to build documentation that lasts:
W - Where it lives matters most. All docs in the repo. No external wikis for code documentation. Period.
R - Review docs in PRs. If a PR changes behavior, the reviewer checks for corresponding doc updates. Add a PR template checklist item: "Updated relevant ADRs or inline comments? [ ]"
I - Incentivize through automation. Auto-generate everything you can. API docs from code. Dependency graphs from imports. Schema docs from models. Automation checks only the inputs and behaviour it covers; review the generated output as the system changes.
T - Trim aggressively. Every quarter, delete documentation that hasn't been viewed or updated in 90 days. Dead docs are worse than no docs because they erode trust in all docs.
E - Enforce with CI. If an ADR references a file that no longer exists, fail the build. If an API example doesn't compile, fail the build. If a README references a deprecated config option, fail the build. The example below uses tsdoc-testify to generate tests and a separately configured Jest run to execute them.[4]
yaml
# GitLab CI example; configure Jest/ts-jest to include *.doctest.ts# Install the dependencies and implement the local check scripts firstdocumentation-check: script: - node scripts/check-adr-references.js # verify ADR file references exist - npx tsdoc-testify --fileMatch "src/**/*.ts" # generate doctest files - npx jest --runInBand # run configured doctests - node scripts/check-dead-links.js docs/ # verify internal links resolve rules: - changes: - "docs/**" - "src/**"
Audit your existing docs. Check view counts. Delete everything with zero views in 90 days. Yes, really.
Start writing ADRs. Begin with your next technical decision. It takes 15 minutes. Keep it in the repo.
Add a PR template item. "Did you update relevant docs?" This alone increased our doc update rate by 3x.
Kill your wiki for code docs. I know this sounds extreme. Move the 5 pages that actually get viewed into the repo. Let the rest die.
Documentation isn't a writing problem. It's a systems design problem. Design the system so that accurate docs are the path of least resistance, and your team will write docs that developers actually read. Fight human nature with a wiki-based strategy, and you'll lose every time.
Frequently asked questions
Does generated documentation stay accurate automatically?
Generation can keep a reference aligned with the input it reads, but stale annotations and incomplete examples can still mislead. Review source material and run checks that exercise the behaviour the documentation describes.
Should an accepted ADR ever be edited?
Preserve the accepted decision and its historical reasoning. When a later decision replaces it, create a new ADR and update the old record's status and replacement link so readers can find the current decision.
What can CI check in documentation?
CI can verify links, file references and executable examples when the team implements those checks. It cannot establish that every explanation is correct. Match each check to a specific failure the team wants to catch.
How do I decide which documentation to maintain?
Look at the reader's task and whether the document is reliable, findable and relevant. Usage data can inform the review, alongside the role of low-frequency material such as recovery runbooks and decision history.
Four years of data from a fully remote engineering team across 4 time zones. Specific metrics on productivity, retention, and onboarding with the frameworks that actually worked.
Small frictions cost more than big blockers. 47 micro-frictions consume 96 minutes per engineer per day. Here's the TAX Return framework for finding and eliminating the developer productivity tax.
A structured 30-60-90 day framework for handling engineering underperformance. Based on 14 real cases with a 64% success rate, starting with diagnosis before intervention.
Developer experience is a systems design problem, not a culture problem. Platform engineering reduces cognitive load from 12 concepts to 3 for common tasks. Here's the LOAD assessment framework.
Seven leadership antipatterns that look reasonable on the surface but quietly destroy engineering teams. Each one includes specific signals, real failure stories, and the framework I use to correct it.
The 10x developer myth is actively harmful to engineering teams. After tracking individual metrics vs team output, I found that the highest performers often had negative correlations with team throughput.