Literate code diffs make the change readable

Video segment: 09:32–10:10

Code needs a reading path

An explainer can give a reader background, intuition, and, where useful, an interactive figure before it reaches code. This segment addresses the next moment: the explanation has reached the actual code change.

The speaker proposes a literate code diff. It is a code-change document in which prose guides the reader through the diff. The prose explains what is about to happen, then the relevant code appears. Files are shown in an intentional order instead of arriving as a bare list of changed files.

What the speaker proposes: explain each part before showing its file, so the explanation accumulates as the reader moves through the change. The goal is to make the change easier to follow than a raw diff and readable away from the IDE.

Here, a diff is the usual source-control view of what changed: added, removed, and modified lines, typically grouped by file. A raw diff is useful evidence. It tells a reader which lines differ. But it does not automatically tell them why the files belong together or which idea to understand first.

Teaching definition: literate means written for a person to read and learn from. A literate code diff does not change the code or replace version control. It changes the presentation around the code so that the reader gets a guided explanation rather than having to reconstruct the whole story alone.

Reading note: The speaker's proposal is stated in the callout above. The definitions, mechanisms, comparisons, and invented example below are teaching explanations unless they identify a specific source detail.

Why all the changed lines are not enough

A raw diff can be complete and still be hard to understand. Imagine seeing four changed files with no introduction. To make sense of them, the reader must work out several things at once:

• What problem is the change trying to solve?
• Which file introduces the central idea?
• Which files depend on that idea?
• Is a later file implementing the behavior, exposing it in the interface, or checking it?

That reconstruction work is the hidden cost of an unordered file list. The reader has the facts, but not yet a route through the facts.

A bare or unordered diff	A literate code diff
Starts with whichever changed file appears first.	Starts with the purpose and the first idea the reader needs.
Makes the reader infer relationships between files.	Names the relationship before presenting the next file.
Treats every file as a separate local edit.	Builds one accumulated account of a larger change.
Can be correct but difficult to read linearly.	Is organized as a learning path while retaining the code details.

This is the important contrast: code completeness is not the same as code intelligibility. A raw diff may contain every changed line. The reader can still lack a usable model of the change.

The pattern: explain, show, connect

Teaching reconstruction of the sequence described in this segment:

1. State the purpose of the change.
2. Introduce the first relevant file and explain its role before showing it.
3. Show that part of the code change.
4. Explain why the next file follows from the previous one.
5. Continue in an order that lets the reader carry the growing model forward.

The order is doing real work. A change often crosses several parts of a system. For example, one file may define a rule, another may apply it, and a third may show or test the resulting behavior. A file-path order does not necessarily reveal that chain. An explanation order can.

Teaching explanation: prose before a code block gives the reader a question to hold while reading it. Instead of asking, “What am I looking at?”, they can ask, “How does this file carry out the role I was just told about?” The code then supplies a concrete answer. The next prose section connects that answer to the next step.

As a result, earlier sections become context for later sections. The reader does not need to rediscover the whole design at every new file. This is what it means for the explanation to accumulate.

A teaching example: turn a file list into a story

The following is an invented teaching example, not the Zen-garden change from the video.

Suppose an agent adds a rule that only workspace administrators can export an audit report. A raw list of changed files might look like this:

src/routes/export-report.ts
src/authorization.ts
src/components/export-button.tsx
src/routes/export-report.test.ts

All four files may matter. But the list does not say which one the reader should understand first.

A literate presentation could instead use this order:

1. Define the rule — authorization.ts.
   Before the diff, explain that the change puts the permission decision in one shared place. The reader now knows that this file establishes the policy rather than merely changing a helper.

2. Enforce the rule — export-report.ts.
   Explain that the server checks the shared policy before beginning an export. The reader can connect this file to the rule they just saw.

3. Reflect the rule in the interface — export-button.tsx.
   Explain that the interface follows the same permission rule, but that the server-side check remains the decision point. The reader can distinguish the visible experience from enforcement.

4. Demonstrate the behavior — export-report.test.ts.
   Explain that the test records the intended outcome for allowed and disallowed users. Now the test is evidence for a policy and enforcement path the reader already understands.

The code itself has not become simpler by magic. What changed is the order in which the reader meets it. They learn the policy, then its use, then its visible consequence, then the check on the result. That is a causal story, not just a collection of files.

“Readable like a textbook” does not mean hiding the details

The lesson plan summarizes the ambition as making a pull request readable like a textbook. The useful part of that comparison is the sequence:

• introduce the goal before the mechanism;
• introduce a concept before relying on it;
• build later material on earlier material; and
• keep the technical evidence available when the reader is ready for it.

A textbook is not useful because it removes the hard material. It is useful because it gives the hard material a deliberate order. A literate diff applies that idea to a code review or explainer.

It is not:

• a new kind of source-control diff;
• prose that merely repeats every line in English;
• permission to omit difficult code; or
• proof that the change is correct.

The code still carries the implementation details. The prose should instead supply the purpose, relationships, and order that the code alone may not make obvious. Teaching context: this can make review more informed, but a readable narrative is not a substitute for checking behavior or correctness.

Why reading outside the IDE matters

An IDE is an integrated development environment: the programming tool used to browse, edit, and run code. The speaker connects this format to printing and reading the result away from the IDE.

That detail reveals the intended use. A person should be able to follow the change as a coherent document, not only by opening tabs and jumping among files. The IDE is still valuable when the reader needs to inspect surrounding code. But the literate document supplies the first map, so tool navigation is driven by a question rather than by confusion.

Teaching interpretation: being readable away from the IDE is a useful design test. If a reader can state the goal, the main steps, and how the files connect after reading the document, the explainer has given them a working model. They can then return to the IDE for deeper investigation with a clearer purpose.

Visual reference and source boundary

The lesson plan associates about 09:36 with a slide titled “Literate code diffs.” It describes a prose-led code-change document with explanatory sections and an embedded code block, rather than only a raw diff.

The plan also notes an important limit: this segment does not establish the exact layout of the literate diff or the specific files in the Zen-garden change. The file names and order in the example above are therefore teaching material, not a reconstruction of the video example. The lesson-wide frame requests remain unverified, so the visual description should not be treated as evidence for more detailed layout claims.

Lesson connection

In the lesson's sequence, this technique moves from high-level explanation into implementation details. It applies a reader-first approach once actual code is shown, instead of ending the explanation at the first diff.

The following chapter addresses a separate risk: a clear document can feel understandable even when the reader has not learned it deeply. Its quiz technique distinguishes making a change readable from merely assuming that it has been understood.

Takeaway

A literate code diff is a prose-guided, intentionally ordered presentation of a code change. It preserves the code but removes some of the reader's burden of inventing the story that connects the files. By explaining each step before showing it, the document turns a pull request from a list of local edits into a readable account of one change.