Case Study 2 — Deep Dive: When Five Reviewers Disagree

A worked reconciliation. Fictional but realistic — the kind of multi-reviewer pile-up that paralyzes documents every day.

Raj Patel maintains a popular open-source data-pipeline library. (You'll follow Raj's README makeover in Chapters 24–26; here we watch him handle the review side of collaborative docs.) He has drafted a new "Getting Started" guide and opened it as a pull request so the community can review. Five reviewers comment. They do not agree. This is where collaborative writing goes to die — or where a good owner earns the title.

Here are the comments, exactly as left on the pull request:

  • Reviewer 1 (a maintainer): "The intro is way too long — three paragraphs before the first code example. Cut it to one."
  • Reviewer 2 (a new contributor): "I needed more setup context — I didn't know what problem this library even solves until halfway down."
  • Reviewer 3 (a power user): "The example uses pip install, but the docs elsewhere say we recommend uv. Pick one."
  • Reviewer 4 (a maintainer): "The example uses uv — but most of our users are on pip. Use pip."
  • Reviewer 5 (the project lead, who has merge authority): "Whatever you do, the install command in the Getting Started guide MUST match the one in the README. Right now they differ, and that's a bug."

Raj's instinct — everyone's first instinct — is to start applying fixes one by one. He resists, because he knows the trap: a change for Reviewer 1 will collide with Reviewer 2, and a change for Reviewer 3 will collide with Reviewer 4. He collects all five comments first and reconciles them in one pass (§23.7).

Classifying the conflicts

Raj sorts the comments into the three kinds of conflict (§23.7), because each is decided differently.

Reviewer 1 vs. Reviewer 2 — a conflict of judgment. "Cut the intro" vs. "add more context" look opposite, but Raj applies the key move: separate the problem from the prescription. What are both reviewers actually reacting to? Reviewer 1 is impatient to reach the code; Reviewer 2 is lost on what the library does. Those aren't opposite problems — they're two readers wanting different things from the same paragraphs. The underlying issue is that the intro is doing the wrong job: it's long but doesn't quickly say what problem the library solves. The fix is neither "cut" nor "expand" — it's restructure: one tight paragraph that states the problem and the solution in three sentences, then straight to code. That single change serves both reviewers — Reviewer 2 gets the "what does this solve" answer fast, and Reviewer 1 gets to the code fast. Two opposite prescriptions, one fix to the shared problem.

Reviewer 3 vs. Reviewer 4 — also a conflict of judgment (pip vs. uv). Both have a real point: uv is the project's stated recommendation; pip is what most users actually run. Raj decides by audience and purpose (§23.7, Chapter 2's question): the audience for a Getting Started guide is a brand-new user who almost certainly has pip and may never have heard of uv. So the primary example uses pip (Reviewer 4 wins on the main path) — but Raj honors Reviewer 3's concern by another route rather than ignoring it: he adds a one-line callout, "We recommend uv for faster installs — see the Advanced Setup guide." Reviewer 3's point (the project recommends uv) is preserved without making a new user detour through an unfamiliar tool. The declined prescription, the honored concern.

Reviewer 5 — a conflict of authority, and the constraint that governs. The project lead, who holds merge authority, has stated a hard requirement: the install command must match the README. This isn't a preference to weigh against the others; it's a constraint set by the person accountable for the project's consistency (§23.7, decided by role). It actually resolves part of the pip/uv debate: whatever Raj picks for Getting Started must also be what the README shows. So Raj checks the README, finds it uses pip, and that locks the main example to pip — aligning with both Reviewer 4 and Reviewer 5. The authority conflict doesn't override the judgment call so much as bound it.

The decision log

Raj writes a short decision log directly in the pull request, so no one relitigates these once a sixth reviewer wanders in (§23.7):

Decision log — Getting Started guide: 1. Intro length (R1 vs. R2): Restructured rather than cut or expanded. The intro now states problem + solution in 3 sentences, then goes to code. Serves both the "too long" and "need more context" concerns — the real issue was the intro doing the wrong job, not its length. 2. Install command (R3 vs. R4 vs. R5): Main example uses pip, decided by audience (new users have pip) and required by R5's constraint (must match the README, which uses pip). R3's uv recommendation preserved as a one-line callout linking to Advanced Setup — concern honored, main path kept simple. 3. Consistency (R5): Verified the Getting Started install command now matches the README. Done.

What made this work

Raj never tried to satisfy everyone, because he saw that some notes were mutually exclusive and "obey all reviewers" was therefore impossible. Instead he decided, and four disciplines made the decisions clean:

  • He collected everything before changing anything. Applying fixes live would have produced ping-pong — uv, then pip, then uv again — as each reviewer's edit undid the last. One reconciliation pass, not five live edits.
  • He looked under the prescriptions for the shared problem. The R1/R2 "conflict" wasn't really a conflict; it was two readers naming the same flaw (an intro doing the wrong job) with opposite-sounding fixes. The restructure dissolved it.
  • He decided judgment calls by audience, not by volume or seniority. The pip/uv call turned on who the guide is for — a new user — not on which reviewer argued hardest.
  • He honored declined notes' real concerns by another route. Reviewer 3 didn't get uv as the main example, but the reason behind the note (the project recommends uv) got into the document as a callout. Declining a prescription is not the same as dismissing a concern.

The result: a Getting Started guide that's tighter than Reviewer 1 wanted-by-cutting, clearer than Reviewer 2 feared, consistent as Reviewer 5 required, and respectful of Reviewer 3's recommendation — produced not by compromise-into-mush but by judgment, classification, and a log that closed each question for good. Five disagreeing reviewers, one calm decider, one shipped document.