09-14
Healthy Documentation: A CTO's Case for Docs-First Engineering
A CTO's field notes on running a docs-first engineering culture: replace half-hour check-ins with a one-page memo, budget documentation time explicitly in estimates, and require a short "why X over Y" paragraph on every merged feature. He is candid about the failure modes — stale pages are worse than none, and some workarounds should be fixed in code rather than explained in three paragraphs of handbook. Concrete mechanisms include a lightweight CI check that fails the build when a new analytics event ships without a matching wiki entry, ADR and post-mortem templates, the Diátaxis split between tutorials and reference, and a part-time "docs gardener" who prunes dead links.