mediumScenarioBehaviouralMidSeniorStaffLead
An engineer who knows the system better than anyone sends you a badly written docs pull request. What do you push back on?
Review a docs PR by blocking only on things that make a reader fail: wrong facts, missing prerequisites, unsafe order or untested commands. Fix mechanical style yourself, leave harmless voice alone, and keep the expert willing to contribute again.
4 min readUpdated 2026-08-15
Answer
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.
Was this answer helpful?
Likely follow-ups
- The engineer disagrees that the prerequisite is missing because it is obvious to them. How do you settle it?
- What would you do differently if this were the third badly structured PR from the same person?
- How do you review a page describing behaviour you cannot test yourself?
- Which style rules are worth a linter and which are not worth enforcing at all?
Related questions
- Tell me about a time you had to work closely with someone you found difficult.mediumAlso on collaboration5 min
- Tell me about a time another team was blocking you and you had no authority over them.mediumAlso on collaboration6 min
- You may use an AI coding assistant in the machine-coding round. What do you still write yourself, and what do you ask it for?mediumAlso on code-review5 min
- The assistant wrote a working solution and the interviewer asks for its complexity and one input that breaks it. How do you verify code you did not write?mediumAlso on code-review5 min