Diffs must show the actual change, not a whole-block swap

What it is

Comparing two versions, people need to see what changed: which word, which number, which image. If the algorithm treats a whole paragraph as a swap—deleted on the left, inserted on the right—the few letters that actually moved are buried in a red-green slab, and both rollback and review become a full read. This is grain of the delta. Whether the history list opens, and how autosave versus explicit save is marked, do not replace this layer.

Why it happens

People find difference by matching local pieces. Whole-block replace is computational laziness: a moved sentence or a changed punctuation flips a hash, and the paragraph is marked delete-plus-add. Working memory cannot align the same sentences across two long blocks, so people abandon the compare or treat unchanged sentences as new. Word- or sentence-grain leaves unedited context still, and the eyes can land. Structural edits (heading promoted, list turned into a paragraph) should be marked as structure, not body replacement. Tables and numbers suffer most from row-level replace: one cell changes, the whole row goes red, reviewers cannot see which number. Grain down to every space is noise; fold meaningless whitespace, still pointing at the actual change rather than swapping a slab.

Studying it

Three edits: one word inside a paragraph, a moved sentence, one cell’s number. Compare whole-paragraph red-green, word highlight, cell-level table diff.

Independent variables: smallest unit (paragraph / sentence / word / cell), whether a move is recognized as a move, whether whitespace is folded. Dependent variables: time to the changed place, unchanged sentences treated as new, whether reviewers can restate which number moved.

Material must be longer than a screen or whole-block cost never appears. Do not use programmer diff markers as the only UI. Images and canvas objects need object-level deltas; a text diff is not a substitute.

Where it stops holding

Encrypted or binary attachments cannot word-diff; say “binary, whole-file replace” rather than fake a body delta. Word-grain on huge files may time out; start at paragraph and expand on demand, but the default should not stop at chapter-replace. Mixed scripts and right-to-left word breaking can fail; fall back to sentence grain and say tokenization may be wrong, rather than paint false red-green.

Applying it

• Default text grain is word or sentence; unedited context stays put. Recognize sentence moves instead of delete-plus-add.
• Tables grain at the cell; highlight the changed cell, leave the rest of the row still.
• Offer a “changes only” view that skips unedited sections.
• Verify: change one number and one word; people should point at them in the compare view. If they must read a whole red-green paragraph to find them, grain is still whole-block. Move a sentence and check it is marked as a move.

Related

• Within the group: H8.11.1 Rollback must account for unsynced collaborator edits · H8.11.3 Autosave versions and explicit saves need distinct marks · H8.11.4 Overgrown history needs a merge policy so the list stays readable
• Adjacent: H8.06 Version History · V4.04 Versions, Changesets, and Diffs
• Search terms: inline diff · word-level diff · move detection