Documentation health reviews

Documentation rots quietly. The architecture page describes a system that shipped two quarters ago, the onboarding doc breaks on the fourth step, an endpoint gained a parameter that no page mentions, and none of it announces itself. A documentation health review is the thing that makes someone look. It is a scheduled review that reads a repository and the recent work against it, finds where the docs have drifted from the code, and writes up what it found as a batch of proposals you walk through and approve.

This page is the operational how-to: what a review produces, how a proposal carries the evidence that called for it, how you approve the small edits inside it, and how the batch view lets you move fast on the obvious ones and slow down on the rest. For the pages themselves, how you write, organize, and onboard a repository's docs, read repository documentation and wiki; for why they sit in the platform rather than in GitHub, read repository documentation. For where you put a review on a schedule, see connect a repository.

Gather, analyze, propose, then stop

A review is a Flow that runs against one repository on the schedule you set. It works in three passes, and where it stops is the point of the whole design:

1. Gather. It reads the repository's docs and the work that has happened against the repository since the last review, as far back as the lookback window you set.
2. Analyze. It looks for the gaps: the page that no longer matches the code, the topic nobody documented, the procedure that stopped working.
3. Propose. It writes up what it found as a batch of discrete proposals, and stops there, in front of a person.

The review does not change a single page on its own. It surfaces what it believes should change and hands the decision to you.

That stopping point is deliberate, and it is the difference between a tool you trust and one you turn off. A review that edited your docs unattended would be a review you stopped running the first time it got something wrong. A review that proposes, with its evidence attached, and waits for a person, is one you can leave running, because the worst it can do is suggest. Every change that reaches a page passed a person first.

When a review runs and finds nothing worth proposing, it says so and closes quietly rather than inventing busywork. A run that produced no proposals is marked as much, and it tells you why it was quiet: no sessions in the window, or signals reviewed with no doc gaps found, so a quiet week reads as a quiet week rather than a failure. A run that errored or is still working shows up too, with its state and reason, so the schedule is never a black box you have to wonder about.

You do not have to watch the schedule for the runs that do find something. When a run lands proposals, your owners and admins get a notification that links straight to the batch, so the review reaches the people who can act on it without anyone refreshing a tab.

A proposal carries its evidence

The reason a health review is worth reading, when most automated suggestions are worth ignoring, is that it does not guess. Every proposal is built from signals: concrete moments captured as work happened. Each one is stamped with the session it came from, the person involved, and an excerpt you can trace back. A proposal is not the agent's opinion that a page looks old; it is a position the agent reached from things that actually occurred.

Ten kinds of signal feed a review:

Two of these come straight off the PR review loop: a finding a reviewer raised, and a comment thread that pointed at a page instead of the code. The review you ran on a pull request last week becomes evidence the documentation review reads this week.

Each proposal lists the signals behind it, so when you accept a change you are accepting the platform's read of real evidence, not a hunch. The signals are the why; the proposed edit is the what. You get both.

Every proposal also declares what kind of change it is and how confident the review is:

• An update revises an existing page, and it comes as a set of small edits rather than a rewrite (the next section is about exactly this).
• A new page fills a gap the docs clearly have.
• A restructure reshapes a page that has outgrown its layout.
• A deprecation retires a page that no longer reflects how the system works.

An update is the only kind that comes apart into separate edits. A new page, a restructure, or a deprecation is a whole-document change, reviewed as a single before-and-after diff and approved as a unit, and for those you can rewrite the proposed text yourself before you approve it, so the page lands in your words rather than the review's.

Confidence is high, medium, or low, and it is not a vibe. It tracks how directly the signals point at the change: a stale reference the agent hit and a reviewer's comment both naming the same line is high; a single repeated question that might mean a page is unclear is low. The dial is the review telling you how much of its own reasoning it would stand behind, which is exactly what lets you take the obvious changes as a group and give the uncertain ones the attention they need.

What a good proposal looks like

The test of a health review is not how many proposals it raises. It is whether the proposals are ones a person says yes to without second-guessing the whole tool. A good one has three properties, and they map onto the three things the surface shows you.

It points at evidence you can trace, not a feeling that a page looks old. "Three signals say the auth endpoint moved to v2: Sarah's correction in chat, a stale reference the agent hit, and a reviewer's PR comment" is a proposal you can check in thirty seconds by opening the signals. "This page seems outdated" is not, and a review that raised the second kind is one you would stop reading by the second week. Every proposal here is the first kind by construction, because it is built from captured signals rather than a pass over the prose.

It proposes the smallest change that fixes the problem. A version number that moved gets an edit that changes the version number, not a rewrite of the page it sits on. The narrower the proposal, the faster the yes, and a review that consistently proposes narrow is one you can clear over coffee. The next section is about exactly this discipline.

It tells you how sure it is, and it is right to be unsure sometimes. A proposal that claimed high confidence on a single ambiguous signal would teach you to distrust the badge. One that marks itself low when the evidence is thin is telling you the truth, which is what lets you trust the high-confidence column enough to take it as a group. A review that is honestly uncertain where it should be is worth more than one that is confident everywhere.

Small edits, not rewrites

A rewrite is hard to trust. It touches everything at once, a reviewer has no clean way to read it line by line, and the result is accept-the-whole-thing or reject-the-whole-thing. So an update proposal is never a rewrite. It is a list of surgical edits, and each edit names the exact text it wants to replace, the text it wants to put there, and the reasoning behind it.

You decide each edit on its own: approve it, reject it, or edit the replacement before it lands. You read them in whichever view fits, the changes inline, the edits on their own, or the old and new side by side, and you can filter a long proposal by what is still pending, approved, edited, or rejected as you work down it. The proposal does not move until every edit has a decision, and when it applies, only the approved edits are written.

This is what makes a mixed proposal useful instead of frustrating. Picture a proposal on a config page that carries five edits. Two swap a renamed flag and you approve them on sight. One rewords a warning in a way that reads cleaner but drops a caveat that mattered, so you reject it. Two more rename a parameter that did move, but to a name your team has not settled, so you click Edit, type the name you actually shipped, and approve your own wording. Four edits land, one of them in your words, and the misread never touches the page. A rewrite would have made you choose between keeping the dropped caveat and throwing away four good edits. Surgical edits never put you in that trade.

When the page moved underneath the proposal

A proposal is written against the page as it was when the review ran. By the time you review it, the page may have changed, and an edit's target text may no longer be where it was. The platform handles this rather than applying a stale edit blindly, and it handles the two cases differently because they are different problems.

If a single edit's target text no longer matches, the drift is recoverable. The platform flags that edit so you can reject it cleanly and apply the rest, and the proposal records as partially applied. One anchor going stale costs you that one edit, not the whole analysis. If the page the proposal targets has been deleted or moved out from under it entirely, the drift is blocking: the proposal holds at the apply step and surfaces the reason, so a person decides what to do rather than the platform writing into the wrong place. Apply fails closed, never into the wrong page.

A proposal, from correction to page

Three weeks ago Sarah was in chat with an agent that cited the old auth endpoint. "No," she told it, "that moved to v2 last sprint." The correction was captured as a user correction signal, stamped with her session, and then nothing happened, because one correction is not yet a pattern.

The next Monday the weekly health review runs against the repository. In its lookback window it finds Sarah's correction, a stale reference signal from a different session where the agent searched the auth page and hit the v1 URL, and a PR comment where a reviewer noted the docs still said v1. Three signals, one page. The review writes an update proposal against the auth doc, marks it high confidence, and stops.

Priya opens the batch Monday morning. The auth proposal sits near the top. She expands it: two surgical edits, each naming the exact v1 string it replaces with v2 and the reasoning, and a Signals panel she opens to read Sarah's own words from three weeks ago. She approves both edits and clicks Apply 2 edits. The auth page updates in the document store, and the proposal records who approved it and the three signals it was built from, so the next person who asks why the page changed has the whole answer in one place.

Nothing reached the page that Priya did not choose. The review's job was to notice, to gather the evidence, and to write the change small enough to say yes to in a morning.

The loop that keeps docs current

The reason a health review works where a documentation sprint does not is that it is not a one-time push. It is a loop, and the loop runs on the same work that breaks the docs in the first place.

Every day, the work generates signals whether anyone is looking or not. An agent searches for a page that does not exist. A reviewer's comment lands on a pull request the docs should have answered. Someone corrects an agent in chat. A documented step fails when an agent follows it. None of these is an alarm; each is a quiet mark left in the record, captured the moment it happens and stamped with where it came from.

The scheduled review is what turns that drip of marks into a decision. It reads the window of signals since it last ran, finds the ones that point at the same page, and writes them up as a proposal with its evidence attached. The signal that was invisible on Tuesday is a high-confidence proposal in Monday's batch, because by Monday two more signals agreed with it.

A person closes the loop, and closing it feeds the next turn. The approved edit lands on the page, the proposal records who approved it and the signals behind it, and the next time an agent reads that page it reads the corrected version, so the correction that started as one reviewer's comment stops generating the same signal. The loop does not end; it quiets down where it is working and stays loud where the docs are still drifting. The drift you fix stops talking; the drift you have not reached keeps raising signals until a review reaches it.

Reviewing a batch

Priya's auth proposal did not arrive alone. Every run hands you its proposals together, as one batch, and the batch view is where you triage them. You filter the runs by status and by date, and every proposal in a batch wears its change type and confidence as a badge, so you can read the shape of a batch at a glance and walk the proposals one at a time, or act on a whole class of them at once. That last part is the dial that decides how much you lean on the review.

The lever most teams reach for is Approve all high-confidence. It applies the proposals the review was most sure about as a group, so the obvious updates, the renamed function, the moved endpoint, the corrected version number, clear in one action while you spend your real attention on the medium and low ones. Its mirror, Reject all low-confidence, clears the noise floor in one move so what remains is worth reading.

A team that wants to move fast bulk-approves the high-confidence column and triages the rest; a team that wants to slow down walks every proposal by hand. The surface is the same; the speed is yours to set.

A bulk action steps over the proposals that are not ready: the ones flagged for revision because the page moved underneath them, and the ones you have already started deciding edit by edit. The obvious changes clear while the few that need a closer look wait for you, so nothing is approved out from under a decision you started.

Across every repository at once

If you run reviews on more than one repository, the documentation reviews page rolls the open proposals up across all of them. This is the lead's view, not the editor's. When ten repositories each surface a handful of proposals a week, the question stops being "is this one edit right" and becomes "where is the documentation debt actually building up." The roll-up answers it: each repository shows its pending count and how many of those are high confidence, so the repository whose docs have drifted furthest from its code is visible before anyone reads a single edit. Repositories with nothing waiting stay off the list, so the view shows what wants attention and nothing else.

What the roll-up turns into is a triage order. A lead does not read ten batches; they read the one number per repository and send the person with the most context at the repository carrying the most pending work. The view does not assign the work, but it makes the assignment obvious, so documentation debt gets paid down worst-first instead of whoever-looked-first. A repository that sits at zero pending week after week is one whose docs are keeping pace, and the roll-up showing it empty is itself the signal that nothing there needs a person.

Why the docs live in the platform, not GitHub

An approved change is written to the repository's documentation in the platform's own document store, the same place the pages live and the agent reads them from, not to GitHub. Keeping the docs in the platform is what lets a health review exist at all. The agent reads the pages from the same store it writes proposals against, and approving a fix is a click rather than a second pull request to open, review, and merge. Docs that lived only in GitHub would make every drift fix carry the full weight of a code change, which is the weight that stopped anyone from making them in the first place.

The edit takes effect on the page immediately, and the record of why it happened lives on the proposal that produced it: the signals it was built from, who reviewed it, and when. A change is never anonymous. It is tied to the evidence that called for it and the person who approved it, which is the provenance that matters when someone asks six months later why a page reads the way it does.

Reading proposals is open to your whole team through doc-proposals.read, so anyone can see what a review surfaced. Approving, editing, rejecting, and applying are held by doc-proposals.review, which rides on your planners, admins, and owners, the people you trust to decide what your documentation says.

Why reviews work this way

Most teams gave up on keeping documentation current, and the honest reason is that nobody was ever paid to do it while everything else was more urgent. A health review does not fix that by trying harder. It fixes it by making the maintenance cheap and the trust earned: the drift becomes a proposal, the proposal carries the evidence that called for it, and the decision to apply it is a click, not an afternoon. The reason the docs stay current is the same reason a pull request stays reviewable, the work arrives as a clear proposal with a rationale, and a person says yes.

For a planner, a health review turns documentation from a chore that never reaches the top of the list into a batch you triage like any other queue, mostly by approving the obvious.

For an engineer, a proposal is a diff you can read line by line: each edit names the exact text it replaces and why, so you approve the two that are right, rewrite the one that is close, and reject the one that misreads your code, the same judgment you bring to any pull request, on a change to prose instead of source.

For a lead, the question stops being "is this edit right" and becomes "which repository's docs have drifted furthest from its code," because the cross-repository view surfaces the debt before anyone reads a single edit, so review time goes where the drift is worst instead of where it happened to surface.

For the person who has to sign off on letting an agent near your knowledge base, the stake is provenance and reversibility: every applied edit is tied to the signals that called for it and the person who approved it, the worst an unattended review can do is suggest, and a change that should not have shipped is a single proposal to look up rather than a forensic hunt through who-edited-what. The agent never writes to a page on its own, and when a change lands, you can always see exactly why.