Building a Documentation Review Process Engineers Will Actually Follow

Somewhere in your company's Confluence, there is a page titled something like "Documentation Review Process." It has a RACI matrix. It has a Slack channel. It has a template with fields for "reviewer," "status," and "last updated." Someone spent real time on it.

And your PRs are still merging without documentation updates.

This is not a mystery. The process was built around what the documentation team needs, not around how engineers actually work. It was designed to solve a documentation problem, and it got grafted onto an engineering workflow that was already moving at full speed. Engineers did not rebel against it. They just kept shipping, and the process sat there, untouched, slowly becoming a monument to good intentions.

The fix is not a better template.

The Only Review That Works Is One You Can't Skip

The most reliable insight from teams that have actually solved this: if documentation updates are optional, they get skipped. If they are required before code ships, they get done.

This sounds obvious. It is also almost never implemented correctly.

The wrong version is a checklist that a human has to manually verify before approving a PR. That creates a bottleneck, generates resentment, and eventually gets waived for "urgent" releases until it is waived for everything. The right version is automated.

A merge gate (a set of automated checks that must pass before a pull request can be merged) can enforce documentation requirements without requiring anyone to remember to ask. A CI pipeline can fail if the OpenAPI specification does not match the code. A GitHub Action can check whether a changelog entry exists before allowing a merge. A linter can verify that public functions have docstrings. None of these require a human to nag anyone.

The key is keeping the gate narrow. Require what can be automatically verified. Do not require what requires judgment. A merge gate that checks for the presence of a changelog entry is enforceable. A merge gate that checks whether the changelog entry is good is a bottleneck waiting to happen.

Google's engineering practices documentation is instructive here: the goal of a review process is not to catch every possible problem, it is to make sure the overall health of the codebase is improving over time. The same logic applies to documentation. A narrow, automated gate that ships with every PR beats a comprehensive manual review that ships with none of them.

Asking Engineers to Write Is Asking for the Wrong Thing

Here is the actual problem with most documentation review processes: they ask engineers to do two things at once. Create the documentation. Then review it.

Writing is hard. Not "hard" in the sense of requiring specialized skill, though it does. Hard in the sense that it requires a different kind of thinking than coding. Kislay Verma put it well: writing requires organizing thoughts clearly, examining them critically, and expressing them clearly. All three steps are taxing. And since not documenting does not block shipping, the task gets dropped.

The solution is to separate the two jobs. Engineers validate technical accuracy. Someone (or something) else handles creation and structure.

When an engineer is asked to "review this documentation," they face a blank-ish page and a vague mandate. When they are asked "are these three parameters correct, and does this code example actually run," they can answer in five minutes. The second task fits inside the engineering workflow. The first one does not.

This also means the review itself has to be specific. Tom Johnson's work on API documentation reviews makes the point clearly: getting engineers to review long content is genuinely hard. The way around it is to break the review into targeted questions, not open-ended requests. Binary questions work. "Is the authentication flow in step 3 accurate?" works. "Does this look right to you?" does not.

There is also a rendering problem worth taking seriously. Reviewing documentation in a pull request, where the reviewer sees raw markup rather than the rendered output, is genuinely confusing. An engineer might see deleted lines and assume the information was wrong, not realizing it was moved. Staging environments or preview links for documentation changes reduce this friction significantly.

Not Every Doc Update Is a Fire Drill

One of the fastest ways to kill a documentation review process is to treat every update as equally critical.

A typo fix in an internal README and a change to a public API authentication flow are not the same thing. Routing them through the same review process means the authentication change gets the same (low) priority as the typo fix, and both get deprioritized when the team is busy.

Risk-based triage solves this. Sort documentation updates into three buckets:

• High risk: Public API changes, authentication flows, security protocols, anything that external developers depend on. These require engineering review before shipping.
• Medium risk: Internal system documentation, onboarding guides, troubleshooting steps. These benefit from peer review but do not need to block a release.
• Low risk: Typo corrections, formatting changes, minor clarifications. Automated checks or no review at all.

A 2024 DevDynamics analysis of the DORA report found that documentation quality, alongside developer experience and flow efficiency, is a key driver of engineering team productivity. Flow efficiency, specifically, is about making sure work does not sit idle. A triage system keeps high-stakes documentation moving through a real review process while low-stakes changes do not accumulate into a backlog that nobody wants to touch.

Getting the Org to Actually Change

None of this works without buy-in from engineering leadership, and buy-in requires framing the problem in terms engineering leaders care about.

Documentation quality is not an abstract virtue. Poor documentation has measurable costs: developers spending time hunting for answers that should be written down, support tickets that could have been avoided, onboarding that takes longer than it should. The argument to leadership is not "we should have better docs." The argument is "here is what our current process is costing us in engineering hours, and here is what a better process would recover."

Roll out incrementally. Start with one team, ideally one that is already motivated. Measure the before state: how long do PRs take to merge when documentation is involved? How often do documentation updates get skipped? How many support tickets reference missing or incorrect documentation? Then implement the merge gate, the targeted review questions, and the triage system. Measure again.

Early wins make the broader rollout easier. They also reveal what needs adjustment before the process is applied at scale.

Anyway. The organizational piece is change management, not process design. The process can be correct and still fail if it is introduced as a mandate from the documentation team rather than as something engineering leadership has decided to own.

What Changes When the First Draft Already Exists

The deeper problem with documentation review processes is that they ask engineers to review something that does not exist yet. The review and the creation are bundled together, which is why both get dropped.

When AI generates the first draft directly from code changes, the dynamic shifts. Engineers are reviewing something that is already 80% correct, because it was generated from the same code they just wrote. The review becomes what engineers are actually good at: spotting what is wrong, not producing what should be there.

Mercari's engineering team found this when they used AI to generate documentation for complex event pipelines. The hours required for engineers to write and review documentation dropped significantly, not because the review was eliminated, but because the creation problem was solved first.

Doc Holiday is built around this model. It generates release notes, API references, and changelogs directly from engineering workflows, then gives teams the structure to validate and scale that output. The review process catches the edge cases. Documentation ships with code instead of lagging weeks behind. The process works because the hardest part of the process, creating the first draft, is no longer the engineer's problem.