Docs & Code Guide

Docs freshness policy: a template with scope, per-class SLAs, owners, and enforcement

A docs freshness policy is one short document that answers five questions: which docs are covered (scope), what kinds exist (classes), how stale each class may get (SLA per class), who answers for each (owners), and what happens when a page blows its SLA (enforcement). Add an explicit exceptions clause so the policy survives its first edge case. The SLA is one clause of the policy, not the policy itself; the template below is complete and short enough to adopt in a week.

Try it free
7 min readFor leads formalizing docs upkeep for the first time

See it as a diagram

Everything below, as a diagram you can edit. Describe yours and see it in seconds.

148/2000• 3 credits left
Try:

No account needed · Editable canvas, not a picture

What a freshness policy contains

Scope draws the boundary: which spaces, folders, and repos the policy covers, and just as important, what it explicitly does not. Classes group docs by decay rate, because a runbook and an ADR should not share an SLA. Each class gets an SLA in days and an owner role, a role rather than a name, so the policy survives staffing changes. Enforcement names the mechanism that notices violations, and exceptions pre-answer the whatabouts that otherwise kill adoption in the first month.

The relationship to a documentation SLA is containment: the SLA numbers are one clause here. Writing the SLA without scope, owners, and enforcement produces a number nobody is bound to; the policy is what binds it.

The template

Check it into the docs repo it governs, at the root, where a reader of any covered page can reach it in one hop. Keep it under a page: length is the leading cause of policy death.

# docs-freshness-policy.yml
scope: >
  Everything under /docs and the Engineering wiki space.
  Excludes /docs/archive, personal drafts, and meeting notes.

classes:
  runbooks:       { sla_days: 30,  owner: on-call rotation }
  architecture:   { sla_days: 90,  owner: owning team tech lead }
  service-pages:  { sla_days: 90,  owner: service owner }
  onboarding:     { sla_days: 180, owner: engineering manager }
  adrs:           { sla_days: ~,   note: immutable, supersede instead }
  generated-refs: { sla_days: ~,   note: regenerated on release by CI }

enforcement:
  - ci: warn on PRs that change infra/ without touching docs/
  - dashboard: pages past SLA, standing agenda item in monthly eng sync
  - escalation: two consecutive missed SLAs moves the page to /docs/archive

exceptions:
  - archived pages carry a banner and no SLA
  - pages generated from source inherit their generator's release cadence
  - a page may be marked frozen with a reason; frozen pages are re-approved yearly

Enforcement that does not depend on willpower

A policy with no mechanism is a wish. The cheapest hook is a CI warning on pull requests that touch architecture-shaped paths without touching docs, which converts the policy from a document people remember into a prompt they see mid-change; the patterns are covered in docs checks in CI. The second hook is a freshness dashboard fed by git dates or the wiki API, surfacing pages past SLA to their owner, with the numbers defined in documentation freshness metrics.

The escalation clause matters more than it looks: archive after two missed SLAs is the policy admitting that an unmaintained page is a liability, not an asset. Without it, the dashboard becomes a wall of shame everyone learns to ignore.

Rolling it out from zero

Order matters. First inventory: list what exists, which the documentation audit checklist structures. Second, cull: archive everything nobody would re-verify, because every archived page shrinks the surface the policy must police. Third, assign owners to the survivors; a policy enforced against unowned pages punishes nobody and fixes nothing. Only then declare classes and SLAs, and switch on enforcement last, starting with warnings rather than blocks.

Teams that run this order backwards, enforcement first, ownership never, get a month of CI noise and a repealed policy. The rollout is four small steps over four weeks, and the cull in week two typically removes a third of the surface before the SLAs ever apply.

The exceptions clause keeps the policy alive

Every policy meets a page that legitimately should not change: an ADR, a postmortem, a design doc for a shipped system. Without a written exception path, these become precedents for ignoring the policy wholesale. The template handles the known cases, immutable records, generated pages, and offers a frozen marker with a stated reason for the rest, re-approved yearly so frozen does not become a synonym for abandoned.

Generated pages deserve their special case: a diagram regenerated from the repository or an API reference built on release is fresher than any SLA requires, and stamping it by hand would be theater. The policy tracks its generator instead, which is one of the quieter arguments for generating what you can.

Adoption in one month

Week 1 inventory, week 2 cull and archive, week 3 assign owners, week 4 declare classes and SLAs and turn on CI warnings. Escalation and dashboards can follow once the basics hold.

FAQ

What is a documentation freshness policy?

A short document, ideally under a page, that states which docs are covered (scope), the doc classes and how stale each may get (SLA per class, such as 30 days for runbooks and 90 for architecture pages), who answers for each class (owner roles), what notices violations (CI warnings, a freshness dashboard, an archive escalation), and the explicit exceptions such as immutable ADRs and generated references.

What SLAs should different doc types have?

A defensible baseline: runbooks 30 days, architecture and service pages 90 days, onboarding guides 180 days. ADRs get no SLA because they are immutable records that are superseded rather than edited, and generated references get no SLA because they inherit their generator's release cadence. Tune the numbers to your change rate; the per-class structure matters more than the exact figures.

How do you enforce a docs freshness policy?

Three mechanisms, in rollout order: a CI warning on pull requests that change infrastructure paths without touching docs, a dashboard of pages past their SLA fed by git dates or the wiki API and reviewed monthly, and an escalation clause that archives a page after two consecutive missed SLAs. Enforcement should start as warnings; blocking merges on docs is usually more friction than the policy is worth.

What is the difference between a docs freshness policy and a documentation SLA?

Containment: the SLA is one clause of the policy. The SLA states how stale each doc class may get; the policy adds who owns each class, which docs are in scope, what mechanism notices violations, and which pages are exempt. An SLA published without those surrounding clauses is a number with no one bound to it.

How should a team adopt a freshness policy from zero?

In this order: inventory the existing docs, archive everything nobody would re-verify, assign owners to what remains, then declare classes and SLAs, and finally enable enforcement starting with CI warnings. The order matters because enforcing SLAs against unowned or dead pages generates noise instead of upkeep. Done as four weekly steps, adoption takes about a month.