To make a video that explains a design doc or a pull request, do not narrate the whole document. Take four things from it: the problem in one sentence, the before and after picture of the system, the one decision a reviewer most needs to agree with, and the rollout and rollback plan. Write those as about 450 words of plain narration, which is three minutes at 150 spoken words a minute, one paragraph per scene. Then turn the script into a drawn, narrated video where each diagram builds as the sentence describing it is spoken, and link it at the top of the doc. The doc stays the source of truth. The video is the way in.

When a video is worth it, and when it is not

Most pull requests do not need a video. A clear description, a screenshot and a short diff are faster for everyone. The video earns its place when the context is bigger than the diff, and the people who need that context are not the people reading the diff.

A useful test: if you would have booked a meeting to walk people through it, a video is probably worth making. If you would not, it is not.

What to take from the doc

A good design doc is written to be complete. A good explainer is written to be followed. They are different documents, and most of the work is choosing.

The problem, in one sentence. Not the history of how you got here. One sentence a new hire would understand.

The current system, then the proposed one. This is where video beats text. Draw the current path, then change it on screen. Reviewers see what moves, what is removed and what is new without diffing two diagrams in their head.

The decision. Every design doc has one choice that the rest depends on. Name it, and say in one or two sentences why you chose it over the main alternative. Leave the full alternatives table in the doc.

The rollout and how to undo it. Flags, phases, the metric you will watch, and what rollback looks like. This is the section reviewers from other teams care about most, because it is the part that can page them.

What you want from the viewer. End by saying exactly what feedback you need and by when.

Leave out the background reading, the full alternatives analysis, the API field list, the cost appendix and the open questions you are not asking this audience about. Those stay in the doc, one click away.

Worked example: moving sessions out of Postgres

Here is a real shaped example. The design doc is titled "Move user sessions from Postgres to Redis" and runs to eleven pages: context, goals, non-goals, proposal, data model, alternatives (Memcached, keeping Postgres with a partitioned table, signed stateless tokens), rollout, risks, cost and open questions.

The video takes six scenes and about 450 words.

Notice what scene 4 does. The doc has a page on three alternatives. The video has one sentence on the alternative people will actually ask about, and a reason. That sentence answers the first comment you would otherwise get.

Notice also that every number is in the narration as a number: 4,000 writes a second, 38 percent, 30 days. Numbers spoken out loud stick. "A lot of load" does not.

Writing narration engineers will tolerate

Engineers are a hard audience for video, mostly because so much technical video is slow. Three rules keep it brisk.

State the claim, then show it. "Sessions are 38 percent of the primary's load" followed by the drawing, not a slow build to a reveal.

Use the names from the codebase. If the service is called session-store, say session-store. If the flag is sessions_read_from_redis, show that name on screen. Reviewers will search for it.

Cut every hedge. "We think it might be worth considering" becomes "We propose". The doc has room for nuance. The video has three minutes.

Read it aloud once before you make anything. Every sentence you stumble on, rewrite shorter.

Make it

1. 1

   Pull four sections out of the doc

   Problem, before and after, the one decision, rollout and rollback. Copy them into a new file and cut each to a paragraph or two.

2. 2

   Write 450 words, one paragraph per scene

   Use the real service and flag names and say every number out loud. End with the exact feedback you want and the date.

3. 3

   Paste it in and keep your wording

   In openCanviz, paste the script, set the length to three minutes, and choose Keep my wording so the narration is exactly what you wrote. Whiteboard style suits architecture: each box and arrow draws as it is mentioned.

4. 4

   Check every label and arrow

   Generated diagrams get the shape right and sometimes get a name or an arrow direction wrong. Compare each scene with your actual system and fix it in the editor, scene by scene.

5. 5

   Swap in your own voice if your team prefers it

   Some teams like hearing the author. Record the narration yourself and replace the generated voice. Otherwise the generated voice reading your script is fine.

6. 6

   Link it at the top of the doc

   One line under the title: a three minute overview, watch this first. Put the same link in the PR description.

Keeping the video and the doc honest

The video is a summary of a document that will change. Two habits stop it misleading people.

Put the doc version on the last scene. "This video describes revision 3, 14 October." When the doc reaches revision 5 and the video is out of date, everyone can see it.

Remake only the scenes that changed. If the rollout plan changes from three phases to four, edit scene 5, not the whole video. Because each scene is its own piece, a change to one leaves the rest alone.

One more thing to check before you paste an internal design doc into any third-party tool: your company's policy on where internal documents can go. Some teams strip hostnames, customer names and internal numbers first. The worked example above survives that fine, because none of its value is in the hostnames.

If the doc is about how a whole system fits together rather than one change, see how to make an engineering architecture explainer for your team. For an API change aimed at the people who call it, how to make a video that explains how your API works takes the consumer's side. And if the doc lives in Google Docs, how to turn a Google Doc into a video covers the export.

Common questions

Should the video replace the design review meeting? Usually it replaces the walkthrough part of the meeting, which is most of it. Keep a shorter meeting for the disagreements, and ask people to watch first. The meeting becomes a discussion instead of a presentation.

How long should it be? Two to four minutes. Past five minutes you are narrating the doc rather than introducing it, and people stop watching at the same point they would have stopped reading.

What about very large pull requests? Make the video about the change in shape, not the files. A migration PR with 140 changed files is best explained as the before and after drawing plus the order in which to review it: start with the schema change, then the dual write, then the readers.

Can I show code in the video? A few lines, when the line is the point, such as a new interface or a config flag. Anything longer belongs in the diff, where people can read it at their own pace.

Who should narrate it? The author, if they are willing. A reviewer who hears the author explain the trade-off reads the doc more charitably. If not, a generated voice reading the author's own words is a reasonable second best.