Docs rot faster than code when nobody owns them.

A README that still says “ask Priya” after Priya left is not documentation. It is a trap. Treat internal docs as a product: known users (future you, new hires, on-call), jobs to be done, and a freshness SLA.

Open handbook with indigo ribbon

If it is not written, it is not owned.

Users and jobs

Write for the stressed reader, not for the author who already knows the system:

User Job
New engineer, day two Run locally and ship a trivial change
On-call at 2 a.m. Mitigate the top incident without guessing
Marketer Publish a page without voice chat with eng
Security reviewer Find where secrets and access live

If the doc only works when the author is online, it is a personal note.

Internal docs diagram

Minimum viable doc set

  1. How to run locally
  2. How to test
  3. How to deploy
  4. Where secrets live (not the secrets themselves)
  5. Architecture one-pager
  6. On-call runbook for the top three incidents
  7. ADR index for major decisions
  8. Ownership table (content, platform, security, incidents)

Doc types and when to use them

Type Use when
How-to Repeatable task with clear success state
Runbook Incident response under time pressure
ADR Architectural decision with trade-offs
Reference API fields, env vars, flag lists
Explanation Teaching mental models for new teammates

Mixing all five into one mega-README guarantees none of them work.

Runbook shape

Every runbook should include:

  • Symptoms (what you see)
  • Impact (who is hurt)
  • Immediate steps (first five minutes)
  • Escalation (who, how)
  • Verification (how you know it is fixed)
  • Follow-up (ticket template)

“Restart the box” without naming the box is not a runbook.

Freshness

Every page gets an owner and a “review by” date. Quarterly doc debt is a real sprint item. Delete wrong pages — wrong docs are worse than missing docs.

Track:

  • Pages past review date
  • Time for a new engineer to first production deploy
  • Incidents where no runbook existed

If you do not measure doc health, it will not be staffed.

Publishing workflow

Docs PRs use the same review culture as code. Screenshots get replaced when UI changes. Broken links fail CI when you can detect them. Unreviewed wiki free-for-alls are how credentials and outdated steps spread.

The on-call test

At 2 a.m., can someone:

  1. Find the runbook in under two minutes?
  2. Identify the system owner?
  3. Execute the first mitigation without Slack access to the original author?

If any answer is no, the doc set is not production-ready.

Anti-patterns

  • Docs only in Slack threads
  • Screenshots of outdated UIs with no alt steps
  • Architecture diagrams last updated before the last rewrite
  • “Ask in #engineering” as the only instruction
  • Customer help center mixed with internal secrets

Relationship to post-launch ownership

Runbooks and access inventories belong with the ownership map. Launch ceremonies without docs are how knowledge walks out the door with a contractor.

Starter outline for a service README

  1. What this service is for (three sentences)
  2. Ownership (team, Slack, pager)
  3. Run locally
  4. Test
  5. Deploy
  6. Configuration reference
  7. Known sharp edges
  8. Links to ADRs and runbooks

Closing

Invest in the paths people actually use under stress. Everything else is wiki folklore.

Need a documentation and runbook pass for a web platform? Start a project inquiry.