Documentation ownership is bound to the component's change flow

What it is

When a component’s public interface changes, in-context copy, runnable examples, and long form must change in the same change, and a named person must sign in review that the guidance is still the same version as the interface. Docs bound to the change flow means the duty hangs on that change record, not on “the docs group will follow up”. If the interface merges first and the guidance is patched later, the point of use is permanently a beat behind; in that beat, consumers read the previous version’s usage.

Ownership is not “someone once wrote docs”. Once-written only proves a historical file. Binding requires: the person who changes a prop also changes the annotation, the person who deletes an entry also deletes the example, and a checklist item that cannot pass cannot merge. Ownership travels with the component, not with whoever feels like writing.

Why it happens

If docs and code run on two queues, the code queue is faster — red tests block a release, yellow docs have no equal gate. Guidance becomes voluntary labour and is dropped when the schedule tightens. The change record folds both artefacts into one atom: interface and guidance enter main together, or they stay out together. Atomicity turns “who writes” from a moral question into a process question: a change that did not update guidance is incomplete, the same as a change that did not update tests.

If ownership is unnamed, the process gate becomes an unclaimed checkbox and is skipped. Named to the component maintainer (or an explicit deputy), the signer is the person who must answer the next time someone asks why the hover still teaches the old prop. Duty is bound to the change because only at the moment of the change does the author see old and new interface at once; a later writer cannot see why something was deleted, and has to guess.

Where it stops holding

Exploratory branches that are not yet public need not update long form on every experiment; binding starts when the interface is declared stable and ready for main. A security hotfix that touches only internals, with public usage unchanged, may skip the docs item if the record states “public interface unchanged” and that claim is reviewed. Translation lag can be scheduled separately; source-language in-context annotations cannot — that is what consumers read. Outsourcing all docs to a group that never changes the code will snap the binding at the handoff, unless that group is listed as a reviewer on the same change record as a maintainer.

Applying it

• Make a hard checklist item: when public props, slots, or defaults move, type annotations, runnable examples, and the versioned long-form link must move in the same change; missing any one cannot merge.
• Write a maintainer in each component’s metadata; the docs reviewer defaults to that maintainer, not to “whoever is free”.
• For deleted or renamed interfaces, delete or expire still-searchable old sentences in the same change, so old guidance does not remain a live entry.
• How to check: sample the last ten changes that touched a public interface and count how many updated annotations and examples in the same commit. For the zeros, hover at the point of use: if it still teaches the old name, binding failed. Then open a change that edits only the interface, not the guidance, and see whether the gate blocks it — if it does not, this is still voluntary labour.

Related

• Same group: R1.12.1 Guidance placed at the point of use is more likely to be read than a docs site · R1.12.2 Examples must run; static screenshots drift from the implementation
• Adjacent: R1.04 Usage guidelines · R1.06 Contribution and governance
• Search terms: docs bound to the change flow · documentation ownership · docs in the PR