Documentation review process: who should approve what

Every engineering team has a review process for code. Almost none have one for documentation, even though a wrong support article reaches customers faster than a wrong deploy does, and takes longer to notice.

The usual objection is that review slows writing down. It does, if you apply it uniformly. The trick is not reviewing everything.

Not every article carries the same risk

Sort your documentation by what happens when it is wrong:

  • Destructive — anything describing deletion, billing, migration, or security settings. A mistake here costs the customer data or money.
  • Blocking — setup and integration guides. A mistake wastes hours and generates support tickets.
  • Cosmetic — feature overviews, changelog entries, FAQ phrasing. A mistake is embarrassing and cheap to fix.

Only the first two need approval before publishing. Requiring sign-off on cosmetic edits is how review processes get abandoned.

Who should approve

The reviewer should be whoever pays the price when the article is wrong.

For destructive articles, that is usually engineering — they know whether the described behaviour is real. For blocking articles, it is usually support, who know how customers actually get stuck. Product rarely needs to approve either, though they often want to.

The failure mode is routing everything to one person. That person becomes a queue, the queue becomes a delay, and the delay makes people route around the process entirely.

Timing matters more than approval

A documentation change is usually written before the thing it documents ships. Publish it immediately and it describes software that does not exist yet; publish it manually afterwards and it goes out days late, if someone remembers.

This is the part most tools handle badly. A draft toggle only has two states, so "approved but not yet true" has nowhere to live. What you want is to approve the change now and have it publish on the release date — and to be told if the article moves on in the meantime, rather than silently overwriting whoever edited it after you.

A model that survives contact

  1. Classify the article — destructive, blocking, or cosmetic.
  2. Route destructive and blocking changes to the team that carries the cost.
  3. Let cosmetic changes publish directly.
  4. Schedule approved changes against the release they describe.
  5. Keep the record of who approved what, attached to the article.

Step five is the one people skip, and it is the one that matters six months later when someone asks why the documentation says what it says.

We are building Annotio around exactly this model — change requests, approvals and scheduled publishing in a knowledge base, rather than bolted alongside one. It is not open to the public yet; you can join the waitlist on the home page.