Video Curriculum Guide
A video curriculum is an ordered set of short videos, each paired with a short post, that teaches a body of knowledge one idea at a time. This guide is the process for making one. It is a living document: edit it whenever a series teaches us something.
The first series built this way was the Keyline explainer (six parts, 2026-10-15, on enuc at ~/keyline-explainer). It showed the format works and also showed the main failure modes: a two-minute video that carries three ideas, narration that never pauses, and diagrams with more on screen than the viewer can take in. The rules below exist to prevent those.
The one rule
Every unit teaches exactly one idea. A unit is one video plus one post. If the script needs the word "also", or a second metaphor, or a "next puzzle", it is two units. Split it.
A good test: can the viewer say the idea back in one sentence, and can that sentence be wrong? "Authority is recomputed from the whole set of certificates every time, not carried in any one of them" passes. "How Keyline sync works" fails.
Phase 1: the curriculum as text
Nothing is rendered, recorded or animated until the curriculum passes review as text. Text is cheap to change; video is not.
1a. Idea map
List every idea the audience must hold by the end. One line each, as a claim.
Mark dependencies: which ideas must be understood before this one makes sense.
Order them so no unit relies on an idea that comes later. Simplest and most concrete first.
Cut anything that is true but not needed to understand the later ideas. Put it in a parking list for a future series.
1b. Unit card
One card per unit, in this shape:
Idea. One sentence, as a claim.
Why it matters. What goes wrong, or what becomes possible, once you hold this idea. This is the hook.
Context the viewer already has. Which earlier units this builds on. Nothing else may be assumed.
Metaphor. One concrete, physical metaphor that carries the idea and no more. Name where the metaphor breaks, so the script does not stretch it past that point.
Misconception. The wrong model the viewer most likely has, and the moment in the script where it gets corrected.
Beats. Five to nine. Each beat is one to three short spoken sentences and exactly one change on screen.
Screen. For each beat, what is on screen in one line of at most ten words. Never more than four things on screen at once. Only things the narration names.
Target length. Usually 45 to 90 seconds, including pauses; the first series ran longer, and every series since has landed between 45 and 65. The idea sets the length. Do not pad a short idea or compress a long one. If it will not fit, split.
Check question. One question the viewer should be able to answer afterwards.
1c. Script style
Write for the ear, then cut.
One sentence per line. The pipeline puts a pause after every line, so a line is a breath.
Short sentences. Ten words is normal, twenty is the ceiling.
Plain words. Say "take back", not "rescind"; "shows", not "demonstrates". A technical term is allowed only when it is the thing being taught, and it is defined the first time it is spoken.
No throat-clearing and no flourish: no "here is the idea", no "that is the whole point", no "put it all together". Say the thing.
No cross-references the viewer cannot use. "Unit seven" means nothing to someone watching unit three. Say what the later unit says, or say nothing.
Read it aloud. If you stumble, cut.
Then write the post from the script. The post is the script with room to breathe: it may add one diagram, one worked example and links, but it must not add a second idea.
1d. Text review
Before anything moves to Phase 2, someone who is not the author reads the whole curriculum as text and answers, per unit:
Is there exactly one idea? Name it.
Does every beat serve that idea? Strike any that do not.
Does the metaphor carry the idea, and does the script stop before the metaphor breaks?
Is everything the unit assumes covered by an earlier unit?
Is the misconception actually addressed?
Read aloud at speaking pace with a pause per line: does it land inside the target length?
Is every claim true to the source? Cite the section for anything doubtful.
Any "no" sends the unit back to 1b. Reorder or split units freely here. The review ends with a signed-off list of unit cards and scripts.
Phase 2: production
Only signed-off units enter this phase. Changes to the idea, the metaphor or the beat order go back to Phase 1, because they change the curriculum, not the video.
2a. Narration
One audio segment per script line, so every line gets its own measured duration and its own pause.
Pauses are part of the script: about 0.7 seconds after a line, about 1.5 seconds after a beat, longer when the screen is changing. Never speed the voice up to fit; cut words instead.
Synthesize, then listen to the whole thing once before animating. Fix pacing in the text, not in the audio.
Record measured durations and word timings per line. Every visual cue hangs off these.
2b. Visual style
One scene per beat. The scene shows only what the beat's screen line names. Four things at most.
One change per beat: something appears, lights, goes dark, or moves. The change happens on the word that names it.
No labels the narration does not say. No side panels, badges, pills, kickers or running headlines. No legend.
Big shapes, thick lines, high contrast. A still from any frame should read at phone size.
The shared visual language is fixed in the curriculum doc. Introduce no shape that is not on the unit's screen lines.
Captions are the script lines, one at a time, in the lower third.
2c. The iteration loop
Build the clearest picture before building the prettiest one.
Storyboard. For each beat, render one still at the moment of its change. Lay the stills out as a sheet. Look at the sheet with the script beside it. Can you follow the idea from the stills alone? If not, fix the screen lines, not the animation.
Animatic. Render the unit at low resolution with narration and the stills cut together. Watch it once without stopping. Mark every moment the picture is behind or ahead of the words, or shows more than the words.
Animate. Add motion only where the storyboard needed it to show a change. Render stills again at each beat boundary and check them.
Render. Full resolution, loudness normalized, reader page rebuilt.
Do one unit through the whole loop before starting the second. The first unit sets the house style; every later unit copies it.
2d. Assembly and publishing
Render, normalize loudness, and build the reader page with each video embedded above its post.
Publish the series as one document with one child per unit, so each unit has a stable link that later units and other series can cite.
2e. Video review
Watch each unit once without the script, then answer the check question from the unit card. If the answer is not obvious from the video alone, the fault is usually in Phase 1, not the animation. Then watch it once more and count the things on screen in the busiest frame. More than four is a fault in 2b.
Toolchain
The current toolchain lives on enuc. The first series is at ~/keyline-explainer with its TOOLCHAIN.md; later series live under ~/videocurriculum/<series>/ and reuse the same tools.
Narration: Kokoro-82M on CPU. One segment per script line in, one WAV plus a duration and word timings per line out.
Animation and render: Remotion 4 with React. 1080p30, H.264/AAC. Stills via the still command for the storyboard and for checks.
Loudness: normalize the final mix to -16 LUFS.
Reader page: a small build script joins videos and posts into one HTML page.
The toolchain is replaceable. The unit card, the script style, the text review and the iteration loop are not.
What the Keyline series taught us
Part 1 carried three ideas: causal encryption, Sedimentree boundaries, and server-side permission checks. It should have been three units.
The wall socket metaphor in Part 2 was the strongest moment in the series. It was planned, physical, and the script stopped where it broke. Every unit needs one of these.
Splitting the edge cases from five parts into six late in the process was the right call, but it happened after animation. The text review exists to make that call before animation.
The narration ran at 1.12 speed with a third of a second between beats. It never paused. Pauses are now part of the script.
Scenes carried a kicker, a headline, a diagram of ten nodes, three pills and a reach ring at once. Nobody can read that while listening. Four things on screen, one change per beat.
Synthetic narration was acceptable for review but will need a human voice for anything public-facing.
Cueing visuals to spoken words rather than timestamps made script edits cheap. Keep that.
An independent text review of the second Keyline curriculum found 13 factual errors and three multi-idea units before anything was rendered. The review pays for itself.
What the Anytwo series taught us
Record every product claim's source statement in the curriculum itself, quoted. The reviewer can only check what it can see; fifteen of the Anytwo review's thirty-four findings were claims I had read in a source but had not written down.
Name the product each unit belongs to when a series spans a transition. One Anytwo unit turned out to be about Anytype's shipping format, and the script now says so.
A unit card's metaphor must be spoken in the script. Three cards named a metaphor the script never used; the reviewer caught all three.
Say what an account is before the first signature. Five units leaned on key pairs that no unit had taught.
Screen lines are the storyboard. Of twenty-six units, the first storyboard pass found only layout faults: fixed-width chips overflowing, labels colliding with locks, lists drawn too small. The ideas did not need to change.
Word cues break on hyphenated words: the narration tokenizer keeps "any-sync" as one token, so a cue on "sync" never fires. Cue on a neighbouring plain word. A local check of every cue against the script, before any render, catches these in seconds.
What the Git series taught us
Give the reviewer a way to run the thing. The Git reviewer verified claims in a throwaway repository and caught a runtime claim ("Git checks the name every time it reads") that every written source would have let through: tampering is provable, not detected on read. For any subject with a command line, the review brief should say so.
A command the audience already uses is still a concept the series has not taught. The rule against rewriting shared commits used pull and push four units before remotes were introduced. Dependencies are on ideas, not on familiarity.
A number in a script needs the source line that gives it. "Ninety days" was the right number for the wrong case; the thirty-day expiry for unreached commits was one manual line away.
When the review reorders units, renumber every form the id takes. Word cues and scene ids used different quote styles, and the rename caught one and not the other; five units rendered nothing until a check compared every scene id against its unit number. That check is now part of the cue checker.
Check the narration outputs before bundling. The synthesis loop died silently between two units and left an empty timings file, which broke the bundle for every unit, not just the one. Sizes of the timing files are a one-line check.
The "second idea" in a unit is often the one that mentions another part of the system: the checkout refusal in the HEAD unit, pushing tags in the tag unit. Replace it with a beat that deepens the one idea, and the unit usually gets better, not shorter.
What the Willow series taught us
Name the protocol a unit describes when the system has more than one. Three sync units taught Confidential Sync's private overlap detection as "how Willow syncs" while the live proposal, the transfer protocol, sends requests in the clear. The reviewer caught it; the fix was one clause per unit and one sentence in the status unit.
One plain word, one meaning. "Fingerprint" meant the payload digest in unit 4 and the region hash in unit 16. The series now says "digest" for the field and keeps "fingerprint" for the spec's own term.
A documentation-only subject still needs an independent reviewer with the pages open. With no implementation to run, the reviewer compared every claim to the raw page text and found three wrong claims, including a handshake credited with a protection the spec gives to the capability binding.
Re-synthesize narration by text, not by line count. The synthesizer reuses audio by segment id, so a rewritten line with the same id kept its old recording; two units were caught only when their word cues failed. The pipeline now compares the recorded text of every segment with the script before bundling.
Never wait on a process name over a flaky link. Wait loops orphaned by dropped SSH sessions carried the script's name in their command lines and made every later process check wait forever; seven hours went to that. Long jobs now run detached with a log, and waits are on output files.
The guide's own target length was wrong. Phase 1b still said 70 to 140 seconds from the first Keyline series while every series since landed at 45 to 65; the reviewer flagged the contradiction and the number is now 45 to 90.
What the Peergos series taught us
A book that describes a mechanism is not a book that describes the current protocol. Five claims were wrong because a page's examples were read as the design: the block access token is a secret paired with a block, not a signature; the hybrid post-quantum seal is on the follow request, not on every share; the username is sent at login, only the password stays. The reviewer found all five by reading the page the claim cited, so cite the page per claim, not per unit.
Carry the source's own caveat. The custom-apps page says its sandbox is not yet sealed because browsers do not block WebRTC; the first draft said "cannot exfiltrate". If a source hedges, the script hedges in the same words.
Review the storyboard sheets one unit at a time before rendering. Four of twenty-four had a layout fault a render would have baked in: an overlapping card, a floating badge, three devices drawn on top of each other. Six stills per unit, read in order, catch these in minutes.
Do not run narration synthesis and rendering on the same box at once. The CPU synthesizer and the six-process renderer slowed each other by roughly half; the render that takes 70 seconds a unit alone took 115. Queue them.
What the AT Protocol series taught us
Dump the sources as text before writing. Forty pages fetched as plain text, plus a one-line sentence extractor, made every quote a search instead of a scroll, and the reviewer could check 218 quotes mechanically: 216 were verbatim.
Date your read and look past it. Four facts were stale on the day the script was written because the sources recorded were months old: the PLC Organization had been founded, Jetstream v2 had history, Spaces had settled, the event rate had tripled. Before writing, read the blog index for anything newer than the pages you recorded.
Speak the metaphor when you write the beat, not after. Fifteen cards named a metaphor the script never said. The guide already required it; the series now writes the metaphor sentence into the beat whose screen draws it and the reviewer checks every card.
Say who holds the key. "No server can forge you" was wrong because the host holds your signing key. When a claim is about trust, say which party holds what, and the exception becomes the lesson: your host can, so you choose it and can leave it.
The cue checker's duplicate-word notes are the first draft's bug list. Every word that appears twice in a beat is a cue that may land on the wrong one; pick a word that appears once.
Open questions
Who does the text review when the author is an agent? Current practice: a second agent with only the guide, the curriculum and the source docs reviews first, then a human.
How long should a series be before it becomes two series?
Should units be published as they pass review, or only as a complete series?
Do you like what you are reading? Subscribe to receive updates.
Unsubscribe anytime