How to Review Documentation in a Pull Request

You will finish with a documentation review that catches wrong instructions rather than comma placement, runs in the same pull request as the code change, and finishes in a few minutes rather than a thread.

Before you start

Two things decide whether this works at all. The documentation change has to arrive in the same pull request as the code, or in a linked one that merges the same day. And the reviewer needs to see it rendered, not as a raw diff, because a diff hides broken lists, dead links and images that fail to load.

If neither is true yet, fix those first. Reviewing markdown diffs from a separate repository a week later is not a lighter version of this process; it is a different and much worse one.

Steps

1. Read the code change before the prose.
   You are reviewing whether the article describes the change, so you need to know what the change was. Reviewing the article on its own reduces you to proofreading.

2. Open the rendered preview.
   A deploy preview, a rendered view, or a local build. Anything that shows the page as a reader will see it.

3. Check the literal strings against the diff.
   Button labels, menu names, field names, default values and error text, character for character. Approximate labels are the single most common reason a reader gets stuck, and they are trivial to catch here and expensive to catch later.

4. Follow the steps once, using only the article.
   Not the code, not your memory of the feature. This is the only reliable way to find the step that was left out because the author already had it configured.

5. View the screenshots at full size.
   Thumbnails hide stale interface, another customer's data, the wrong theme and a cursor sitting in the middle of the frame.

6. Search for what else the change made wrong.
   Grep the documentation for the old label, the old default, the old endpoint. A renamed field usually appears in more articles than the author edited.

7. Comment about the reader, not the prose.
   "A reader who has not enabled billing will stop at step four" is actionable. "Tighten this paragraph" is an invitation to argue.

8. Automate house style so review stays about accuracy.
   A prose linter in continuous integration settles the arguments over serial commas and product capitalisation before a human ever sees them.

9. Approve on accuracy and file the polish separately.
   A documentation pull request held open for wording merges a fortnight after the feature, by which point nobody remembers what it described.

A reviewer can confirm accuracy in seconds. Everything else needs somebody else.

Common mistakes

Reviewing the markdown diff instead of the page. Broken numbering, an image that 404s and a link with a stray bracket all look fine in a diff and are obvious in a preview.

Approving without doing the task. Every reviewer who reads an article and thinks "that looks right" is reading it with knowledge the reader does not have.

Letting the feature's author be the only reviewer. They cannot see their own assumed knowledge. That is not carelessness, it is what knowing the system does to you.

Style arguments in the review thread. Voice, capitalisation and comma preferences are the fastest way to make people stop attaching documentation to pull requests at all.

Splitting documentation into a separate pull request to keep the diff clean. The clean diff merges, the documentation one waits for a reviewer who has moved on, and the two ship a release apart.

When this stops scaling

Documentation review in a pull request works well while the reviewer knows the feature well enough to spot a wrong claim, which in practice means a team where everyone touches most of the product. That is a real and useful range, and within it this is the highest-value review you can add.

The first limit is reviewer distance. Once changes routinely cross areas nobody on the reviewing team owns, approval becomes a rubber stamp on prose that reads plausibly.

The second limit is structural and no amount of review discipline fixes it. Pull request review only ever sees the articles somebody edited. The articles that quietly become wrong are the ones the change never touched: a shared component's new behaviour invalidating pages in five other sections, a renamed setting appearing in screenshots nobody opened. Those never appear in a diff, so they never reach a reviewer. SupportPages reads merged changes and surfaces the existing articles that a change contradicts, which is exactly the set that pull request review cannot show you.

For teams deciding where that Git workflow should live, compare the managed route in Mintlify alternatives with the self-operated route in Docusaurus alternatives. The Mintlify versus Docusaurus comparison isolates the operational trade-off between the two.