explain-diff-html

Explain Diff

Build a rich, interactive explanation of the specified code change as a single self-contained HTML file, written with the clarity and flow of Martin Kleppmann: classic style, engaging, smooth transitions between sections.

Sections

• Background: the existing system relevant to this change. Explore the surrounding code broadly for this. The reader's prior knowledge is unknown, so open with a deep background for beginners, marked as skippable, then a narrower background directly relevant to the change.
• Intuition: the essence of the change, not the full details, with concrete toy-data examples and diagrams used liberally.
• Code: a high-level walkthrough of the changes, grouped and ordered so they are understandable.
• Quiz: five interactive multiple-choice questions so the reader can confirm they actually understood. Medium difficulty: answerable only by someone who understood the substance of the PR, with no gotchas. On click, tell the reader whether they were correct and give feedback.

Format

• One long page with section headers and a table of contents; inline CSS and JavaScript; responsive so it reads on a phone.
• Save outside the repo at /tmp/YYYY-MM-DD-explanation-<slug>.html, today's date first so the files sort by time and stay out of version control.
• Diagrams are built from HTML elements. Pick a small number of diagram families and reuse them across cases: a simplified version of the UI the user sees, to explain UI changes; a system diagram of data flow or communication between components, carrying example data.
• Lists are HTML lists; callouts mark key concepts, definitions, and important edge cases.
• Code blocks are <pre> tags, or a styled div whose CSS includes white-space: pre-wrap; otherwise the browser collapses the newlines. Done when every code block in the saved source has white-space: pre or pre-wrap.