Documentation Revision¶
Artifact revision — instantiates Mental Model Mismatch Repair
Rewrites the reference text — stale wording, missing examples, hidden edge cases — so the correct model is retrievable at the moment of action.
Documentation Revision repairs a mismatch by fixing the words people read. When the wrong model is reinforced by stale wording, a missing example, an undocumented edge case, or a simplification that quietly omits an exception, this mechanism rewrites the reference material so the correct model is stated plainly and — crucially — retrievable when someone actually needs it. Its defining move is expository: it neither changes the system's cues nor puts anyone through a rehearsal; it makes the corrected belief explicit in prose and examples and surfaces the assumptions the old text left implicit. It presumes the locus is already documentation and concentrates on making that text carry the model that the interface or the world failed to teach.
Example¶
A payments API returns HTTP 200 with a body of {"status": "pending"} when a charge is accepted for processing — not yet captured. The docs show a happy-path example that returns "status": "succeeded", and never mention pending. Developers integrating against it write code that treats any 200 as a completed payment, then ship bugs where orders fulfill before money settles. Documentation Revision rewrites the reference: it adds the pending case to the status enumeration with a worked example, states the previously implicit assumption in bold — "a 200 means accepted, not captured; poll or await the webhook before fulfilling" — and adds an edge-case note for the pending → failed transition the old text hid. The corrected model now lives at the exact page a developer reads while integrating. The revision changes no code and no interface; it makes the true contract legible.
How it works¶
- Find the reinforcing text. Locate the sentence, example, or omission that teaches or permits the wrong model.
- State the corrected model in prose. Write the belief the reader should hold instead, small enough to remember but rich enough to keep the exceptions.
- Surface the buried assumptions. Make explicit the edge cases and preconditions the old text left implicit — the difference between accepted and captured, the states that were never enumerated.
- Place it where action happens. Put the correction on the page a reader consults at the moment of use, not in a distant appendix, so the model is retrievable under time pressure.
Tuning parameters¶
- Correction depth — a one-line clarification versus a rewritten section with examples and an edge-case table. Deeper revision fixes more of the model but risks burying the key point.
- Example density — how many worked cases to include; more examples teach the exceptions but lengthen the page and can overwhelm the core rule.
- Placement — inline at the point of use versus a dedicated "gotchas" section. Inline is retrievable under pressure; separate keeps the main flow clean but is easier to miss.
- Assumption explicitness — how many previously implicit preconditions to spell out; more completeness prevents adjacent errors but courts the wall-of-caveats that readers skim past.
When it helps, and when it misleads¶
Its strength is reach and precision: text scales to every reader at near-zero marginal cost, and it can carry nuance a terse interface cue cannot. It is the natural antidote to the curse of knowledge[n1] — the reason the original author omitted the assumption in the first place — because revision forces the tacit precondition onto the page.
Its failure mode is the documentation that is complete yet unread: a technically perfect edge-case note buried three scrolls down does not repair a model that fails at the moment of action, because a corrected model people cannot retrieve when they need it is no repair at all. Its classic misuse is treating documentation as the universal fix — writing a paragraph to explain away a cue the interface should simply have made honest, quietly shifting the burden back onto the user to read carefully. The guarding discipline is to ask whether the mismatch really belongs in the text or in the system, and, when text is right, to place the correction where it is retrievable under pressure rather than merely present in the archive.
How it implements the components¶
model_revision_path— writes the corrected belief explicitly in prose and worked examples, sized to be remembered yet complete enough to preserve the exceptions.assumption_map— surfaces the preconditions and edge cases the old text left implicit (accepted-versus-captured, the unenumerated states), making the hidden assumptions readable.
It executes a text repair once documentation is the chosen locus; it does not make the system-side locus decision or change the interface cues themselves (correction_locus_decision) — that is its nearest twin Interface Affordance Redesign, which repairs the affordance rather than the words — and it does not transfer-test the revised model in a scenario (expectation_validation, Simulation-Based Correction).
Related¶
- Instantiates: Mental Model Mismatch Repair — Documentation Revision performs the reference-text repair, making the corrected model retrievable at the point of use.
- Consumes: User Journey Diagnostics or Incident Mental-Model Review — supplies the diagnosis of which belief the text must correct.
- Sibling mechanisms: Usability Testing · Incident Mental-Model Review · User Journey Diagnostics · Interface Affordance Redesign · Simulation-Based Correction · Training Feedback Loop · Expectation Audit
Editorial Notes¶
Form Classification¶
Form family: Intervention, Treatment & Transformation
Rationale: Documentation Revision operates as a direct treatment or transformation intended to change the target state or representation because it rewrites the reference text — stale wording, missing examples, hidden edge cases — so the correct model is retrievable at the moment of action.
Independent corroboration: The frozen evidence defines Documentation Revision as 'Rewrites the reference text — stale wording, missing examples, hidden edge cases — so the correct model is retrievable at the moment of action', so its operative form is Intervention, Treatment & Transformation.
Nearest alternative: Communication, Facilitation & Learning — The operation directly rewrites stale reference text and examples; improved reader understanding is its communicative effect.
Review outcome: Independent reviewer agreement; medium confidence.
Origin Attribution¶
Primary origin: Human-Computer Interaction
Origin pattern: Cross-disciplinary synthesis
Present-day reach: Multi-domain
Rationale: Usability and technical-documentation practice cohered revising reference text when observed user errors reveal a mismatch between written guidance and the needed mental model.
Related originating lineages:
- Library & Information Science — Knowledge maintenance supplied controlled updating of authoritative reference artifacts.
- Psychology — The curse of knowledge explains systematic omissions by expert authors and the need for novice-centered revision.
Review resolution: Both current reviews place documentation_revision primarily in human_computer_interaction; the reconciled classification retains only lineages that materially shaped the mechanism and keeps breadth of origin separate from reach.
Attribution caveat: The artifact is documentation, but the triggering diagnosis is a user mental-model mismatch.
Encyclopedia synthesis: The exact catalogued form synthesizes established practice rather than reproducing a single standard historical label.
Review outcome: Reconciled after independent review; medium confidence.
Notes¶
[n1] The curse of knowledge (Camerer, Loewenstein & Weber) is the difficulty experts have imagining not knowing what they know — which is exactly why documentation omits the assumption a novice most needs. Revision counters it by forcing the tacit precondition to be written down. ↩