An engineer who knows the system better than anyone sends you a badly written docs pull request. What do you push back on?

Short answer

When reviewing a weak docs PR from a strong engineer, block only on reader failure: wrong claims, missing setup, unsafe sequencing or steps you cannot reproduce. Fix mechanical style directly, comment once on patterns, and avoid rewriting harmless voice so the page improves without teaching the contributor that documentation is a punishment.

Sort the findings before you write any of them

The review has three buckets, and conflating them is what makes docs reviews feel like an attack. Bucket one is anything that will make a reader fail: a factually wrong claim, a step in the wrong order, a missing prerequisite, a command with a flag that no longer exists, a warning that appears after the destructive action it concerns. Bucket two is mechanical style - heading levels, terminology that disagrees with the rest of the site, a procedure written as a paragraph instead of numbered steps. Bucket three is voice: rhythm, word choice, sentences you would have written differently.

Only bucket one is a blocking comment. Bucket two you fix yourself, in a commit on their branch, with one comment naming the rule once rather than a comment per instance. Bucket three you leave, and the discipline of leaving it is the part that takes practice.

What actually blocks

A wrong claim blocks, and you find it by trying the thing rather than reading it. That is the difference between a docs review and a copy edit: you run the commands on a clean environment, in the order given, and note where you had to know something the page did not say. A page that works only for the author is the single most common defect in a contribution from a subject-matter expert, because the environment they tested in already had the credentials, the feature flag and the local database.

A missing prerequisite blocks for the same reason and is harder to see, because it is an absence. The expert knows the service needs the migration run first, so the sentence saying so was never a sentence - it was an assumption. Asking is better than asserting here: "I hit an auth error at step 3 on a fresh checkout - is there a setup step missing, or did I do something wrong?" leaves them the expertise and gets the same fix.

Placement of a warning blocks even when the warning is present and correct. Readers of a procedure execute as they read, so a caution below the command has already been read too late.

<!-- Before: technically complete, and the reader has already lost the data -->
Run `svc reset --hard` to return the cluster to a clean state.

> Note: this drops all tenant data and cannot be undone. Take a snapshot first.

<!-- After: the order matches the order the reader acts in -->
Before resetting, take a snapshot - `svc reset --hard` permanently drops all
tenant data and cannot be undone.

1. `svc snapshot create --name pre-reset`
2. `svc reset --hard`

Nothing in the rewrite is new information. The only change is that the sentence the reader needed first now comes first, which is most of what editing a procedure consists of.

Why over-editing is expensive

Twenty-two comments on a docs PR, of which eighteen are style, reads to the author as a verdict on their competence rather than on the page. The predictable outcome is not a better second draft; it is that the engineer decides documentation belongs to whoever cares that much about commas, and the next time they change the system they change it silently. You have then traded a slightly awkward page for a permanently absent one, which is a much worse trade than it looks in the moment.

So the arithmetic to hold in mind is that the deliverable of this review is two things: a page a reader can follow, and an author who sends the next one. If a comment does not serve either, it does not get written. Teach one rule per review rather than the whole style guide, and let mechanical rules be enforced mechanically - a linter that flags heading order, a terminology list, a page template with the prerequisites section already in it. A rule enforced by a tool is a fact about the repository. The same rule delivered by a person is an opinion the author is entitled to argue with, and often will.

The failure that runs the other way

The reviewer who only edits prose is the more dangerous of the two failure modes, and it is worth saying so unprompted. A page that has been polished into fluency but never executed now carries confident, well-structured wrong instructions, and readers trust it more precisely because it reads well. If you have to choose - and on a busy day you do - verify the procedure and leave the prose rough. Awkward and correct is a usable page; elegant and wrong is a support queue.

What separates a strong answer here

Anyone can produce the list of things to fix. What an interviewer is listening for is whether you will name something you would deliberately leave alone, and whether you can defend that choice against the obvious objection that your job is to make the page good. The answer is that your job is to make the documentation good over time, and the supply of contributions from people who understand the system is the scarcest input to that.

---

© 2026 Preptima. Originally published at preptima.com.