Documentation Review for Cooperative Expectations¶
Review practice — instantiates Cooperative Communication Repair
Audits a document against the cooperative expectations — clarity, grounding, relevance, sufficiency — before any reader hits the breakdown, and bakes the fixes back into the template.
Documentation Review for Cooperative Expectations is an anticipatory repair: a second reader audits a written artifact — a runbook, spec, policy memo, help article — against the cooperative expectations before it ships, so that the breakdown a future reader would have hit is fixed while the author can still fix it. Its defining move is that it repairs an exchange that has not happened yet. Every other mechanism in this family reacts to a live breakdown in front of real participants; this one simulates the reader who is not in the room, asks whether the document will read as clear, grounded, relevant, and sufficient to that person, and flags each passage that will not. And because a document is a durable artifact, the review closes a second loop the live mechanisms cannot: recurring flaws are written back into the template or style guide, so the same gap is caught structurally next time rather than re-discovered by another reader.
Example¶
A site-reliability team is about to publish a new incident runbook to a 30-person on-call rotation, most of whom have never touched the service. A reviewer runs it against a cooperative-expectations rubric, reading deliberately as the least-informed future on-call engineer at 3 a.m. She hits the line "restart it if needed" and flags it: it fails clarity (restart what, with which command?), evidence (needed how — what symptom triggers this?), and sufficiency (no expected result, no escalation path, no owner). She rewrites it to a five-part step — trigger symptom, exact command, expected output, who to page if it fails, and the escalation threshold.
Two more runbooks that week trip the same missing-owner gap. Rather than fix each in place and move on, the reviewer promotes the fix into the runbook template: every future runbook now ships with a required "Owner / escalation" field the author must fill before publishing. The breakdown that would have cost a bleary engineer twenty minutes and a bad guess is repaired before anyone reads it — and then engineered out of the next document entirely.
How it works¶
- Apply the cooperative expectations as an explicit rubric. Clarity, grounding, relevance, sufficiency, and next-action become review criteria the document is scored against, not vibes.
- Read as a proxy for the least-context real reader. The reviewer deliberately drops the author's insider knowledge and reads for where an outsider would stall.
- Flag each weak passage by which expectation it fails. Not "this is bad" but "this fails grounding" or "this fails sufficiency," so the fix is targeted.
- Promote recurring flags into the template. A gap that shows up repeatedly is written into the standing template or checklist, converting a one-off fix into an enforced norm.
The distinguishing discipline is reading against your own context: the review is only as good as the reviewer's willingness to un-know what the author knew.
Tuning parameters¶
- Rubric strictness — how high the bar on each expectation. Stricter catches more but slows publishing and risks defensive over-documentation.
- Reviewer distance — how naive a proxy reader the reviewer plays. A more distant proxy surfaces deeper gaps but may flag context that's genuinely safe to assume.
- Promotion threshold — how many repeats before a fix becomes a template requirement. Low thresholds harden norms fast but can ossify a template with rules that fit one team's quirk.
- Coverage — spot-check versus full audit. Full audits are thorough but expensive; spot-checks are cheap but miss.
When it helps, and when it misleads¶
This mechanism earns its keep on artifacts that are read many times, asynchronously, by people who cannot ask the author a follow-up — exactly where a live clarification is impossible and a buried gap compounds across every future reader. Fixing it once at the source, and then in the template, has enormous leverage. Its central obstacle is the curse of knowledge:[n1] the author literally cannot see the gaps because they already know the missing piece, which is why the fresh, deliberately-naive reviewer is the whole point.
It misleads when the reviewer shares the author's context — two experts reviewing each other's docs reproduce the same blind spot and sign off on the same hole. It can also over-correct into bloat, padding every document with defensive background until the sufficiency problem flips from too-thin to too-thick, and it can decay into bureaucratic gatekeeping where the review exists to enforce house style rather than reader coordination. The guarding discipline is to use a genuinely low-context proxy reader — or the real audience's past questions — as the yardstick, and to review for whether a reader can act, not whether the prose matches a preference.
How it implements the components¶
cooperative_expectation— it turns the expectations (clear, grounded, relevant, sufficient) into the explicit rubric the artifact is audited against.violated_expectation_diagnosis— each flagged passage is labeled by which expectation it fails, so the fix repairs the right thing.communication_norm_record— recurring fixes are promoted into the template or style guide, recording the repaired norm so it holds for the next document.
It does not detect and name a breakdown as it unfolds live in a room (communication_breakdown — Meeting Repair Move, its nearest twin) or calibrate the amount of detail as its main job (sufficiency_boundary — Sufficiency Calibration Checklist). Meeting Repair Move also diagnoses which expectation failed, but does so in the room after the breakdown surfaces; this review does it on a static artifact before anyone reads it.
Related¶
- Instantiates: Cooperative Communication Repair — it applies the repair logic to a document ahead of time, so the reader never encounters the breakdown.
- Sibling mechanisms: Meeting Repair Move · Sufficiency Calibration Checklist · Clarification Script · Evidence Linking · Relevance Reframing · Readback / Teach-Back · Support Triage Question Set · Clarification Protocol
Editorial Notes¶
Form Classification¶
Form family: Assessment, Review & Assurance
Rationale: Documentation Review for Cooperative Expectations operates as a bounded evaluation of existing evidence or work that produces a finding or disposition because it audits a document against the cooperative expectations — clarity, grounding, relevance, sufficiency — before any reader hits the breakdown, and bakes the fixes back into the template.
Independent corroboration: The frozen evidence defines Documentation Review for Cooperative Expectations as 'Audits a document against the cooperative expectations — clarity, grounding, relevance, sufficiency — before any reader hits the breakdown, and bakes the fixes back into the template', so its operative form is Assessment, Review & Assurance.
Review outcome: Independent reviewer agreement; high confidence.
Origin Attribution¶
Primary origin: Linguistics & Semiotics
Origin pattern: Cross-disciplinary synthesis
Present-day reach: Multi-domain
Rationale: Pragmatics cohered cooperative expectations of clarity, relevance, grounding, and sufficient informativeness for successful communication.
Related originating lineages:
- Communication & Media Studies — Editing and technical-communication practice turned those expectations into document review criteria.
- Human-Computer Interaction — Usability testing supplied fresh-reader review at the moment users attempt retrieval and action.
- Psychology — Curse-of-knowledge research established why an informed author needs a fresh reader to detect tacit assumptions before publication.
Review resolution: Both current reviews place documentation_review_for_cooperative_expectations primarily in linguistics_semiotics; the reconciled classification retains only lineages that materially shaped the mechanism and keeps breadth of origin separate from reach.
Attribution caveat: The review criteria are Gricean, while the preventive documentation workflow is an editorial and usability synthesis.
Encyclopedia synthesis: The exact catalogued form synthesizes established practice rather than reproducing a single standard historical label.
Review outcome: Reconciled after independent review; high confidence.
Notes¶
[n1] The curse of knowledge (Camerer, Loewenstein, and Weber) is the difficulty of imagining what it is like not to know what you know — once you understand a system, you systematically overestimate how obvious your explanation of it is. It is the precise reason authors cannot self-review for clarity and a fresh reader must. ↩