A documentation video is reference material: it gets watched by someone who is stuck, mid-task, hunting for one specific concept. That viewing pattern decides everything else — each video must teach exactly one concept, stand alone, match its siblings, and stay cheap to update when the product changes.
This makes docs videos a different animal from a homepage explainer. A homepage video plays once to a curious stranger. A docs video plays to the same user four times over six months, each time at a different point of confusion. Across sixty-odd produced explainers, the ones built for docs followed different rules than the ones built for landing pages — and mixing the two up is the most common mistake we see teams make.
People arrive stuck, not curious
Nobody watches a docs series front to back. They hit a wall — a run behaves strangely, a term in the UI means nothing to them — and they come looking for the one video that unsticks them. Two rules fall out of this directly.
Every video must be watchable alone. The published order can build (and should — more below), but each entry carries its own prerequisites at one-line depth. If your loops video needs the viewer to understand references, spend one sentence re-establishing references, then move on. Don't re-teach; re-anchor.
No "welcome back." Serialized openers — recaps, "in the last video we covered," instructor re-introductions — assume linear viewing that never happens. In our curriculum work the rule is literal: only the series opener carries the full welcome; every other video opens directly on its concept. A stuck viewer gives you a few seconds of patience. Spend them on the thing they came for.
The same pattern sets the target for the series opener, if you make one: its job is orientation, not mastery. The exit state you're after is "I know what I'm looking at now, I can start exploring" — vocabulary, layout, confidence to click around. Coverage belongs to the per-concept videos.
One concept per video, and the video owns it
The unit of a docs series is the concept, not the feature tour. Each video argues one sentence — "the log records every step, and you debug by reading it backwards" — and everything on screen exists to make that sentence feel obvious. If you can't state a video's sentence, you have a topic, not a video, and topics absorb unlimited runtime because they have no finish line. (This is the series-scale version of one idea per scene.)
Ownership is the part teams miss. In a series, each concept lives in exactly one video, and neighboring videos defer to it by name. When we plan a curriculum, the plan literally annotates this: one video owns "what an agent block is"; the rest own "what you hand it." When two videos both half-teach a concept, both fail — each one assumes the other covered the hard part, and the viewer who watches either walks away with half a model.
Ownership is also what makes the series findable. A stuck user searches for their confusion. A video that owns one concept can carry that concept as its title; a video that covers three things has a vague title, and vague titles lose the search that matters.
Two planning tools make ownership stick:
- A "deliberately not taught" list, per video. Every concept has neighbors, and the neighbors are the threat. Write down what each video refuses to cover and where that content lives instead — another video, a docs page, a screen recording. Scope isn't what you ran out of time for; it's a list of named exclusions with destinations.
- An altitude ceiling for the whole series. Decide the deepest mechanism level any video may reach, and name one video as the ceiling. A docs video enriches the viewer's causal model of what the product does — only enough mechanism to make behavior predictable. If a video is explaining how the algorithm works under the hood, it's too deep; reframe to what it does and when you'd reach for it.
Consistency: a series is a curriculum, not a playlist
A docs series gets judged as a set. Different visual styles, different scene grammar, different voices across entries read as neglect — and worse, they force the viewer to re-learn how to watch with every video.
Sequence it like a course:
- Start with the gravity center. Find the one concept every other concept is defined in terms of, and teach it first. In one product we worked from, that was workflows — tables are read by them, logs record them, deployments expose them. Until the viewer has that object, nothing else has anywhere to attach.
- Group into tracks with an arc. A track about one object runs object → verbs → universality: what it is, what you do with it, why it composes with everything else. Each entry owns one link.
- Never frame by a fixed count. "The Five Operations" dates the moment you ship a sixth. Name the capability; counts are never the lesson.
- Keep one visual system. Same layout grammar, same color meaning, same pacing constants across every entry. Sameness that would be boring in a marketing reel is exactly right in reference material — the viewer should spend zero attention decoding the format.
Length: docs videos run short. Our produced concept videos run roughly 60–90 seconds each; a full eleven-module course planned out to about eleven minutes of animated content total. If an entry wants three minutes, it's usually two concepts wearing one video. (More on runtime in the length guide.)
Keeping videos true as the product changes
The standard objection to docs video is staleness: "our UI changes every month, and every change turns the video into a lie." The objection is right about the stakes — a video showing last quarter's UI actively damages trust, because docs are where users go to find out what's true. It's wrong that this is unavoidable. Staleness is an economics problem, and you can build for it.
- Ground every on-screen value, and re-derive at every build. Every label, number, and color in our videos traces to a real product source in a grounding table — no row, no value. Product truth drifts, so the table is re-checked against the product every time the video rebuilds, never trusted from the previous version. The table doubles as a staleness audit: when the product changes, you can diff a list instead of re-watching a library.
- Build per-scene, so a change re-renders a scene, not a video. Our videos are built from scene files over one shared set piece. When one screen changes, one scene rebuilds; the approved scenes around it don't get touched. A monolithic timeline makes every product change a full re-edit — which is why most teams' docs videos quietly rot.
- Keep narration as text, timed automatically. In our pipeline the voice is synthesized from prose and scenes re-pace themselves around it, so a renamed feature is a one-line edit and a re-render — a minutes-long fix, not a studio booking. Wording changes are the most common staleness class, so this is where cheap matters most.
- Make "redo" a first-class state. Our plan-of-record marks every video exists / redo / new. Admitting a shipped video went stale and queueing its rebuild is part of the plan, not a failure of it. What kills docs libraries is having no state between "published" and "deleted."
If you're commissioning docs videos rather than building them, this is the economics question to ask any vendor: what does it cost me when one screen changes? If the answer is "a new project," the videos will stale-out within two quarters, whatever they look like on day one.
When a diagram beats a video
Not every docs page earns a video, and the discipline of refusing is what keeps the videos you do make worth watching. We keep a standing "never animated" list per product, and the categories generalize:
- UI procedures. Click-here-then-here content belongs in a screen recording, which is faithful by construction, cheap to redo, and pausable. The routing rule we work by: animate the concept, record the live product.
- Reference facts. Permission tables, config options, limits, API fields — anything a user needs to scan or search. Video can't be skimmed and can't be ctrl-F'd. A table beats sixty seconds of narration every time.
- Setup flows. Install steps change constantly and are read while typing. Text with copy buttons wins.
- Internals. Algorithm deep-dives serve the curious, not the stuck, and they violate the altitude ceiling anyway. A static diagram in a docs page serves that reader better — no diagram earns its keep inside the video.
The test for what's left: does understanding require watching something change? Concepts about behavior over time — data flowing through a system, parallel branches converging, a record accumulating — are where animation teaches something no still frame can. That's the material worth the render. (It's also where showing the real product matters most: a docs viewer knows the UI, and invented surfaces get spotted instantly.)
FAQ
How long should each docs video be? 60–90 seconds is the working range across our produced concept videos. Scenes run 8–12 seconds each, one idea per scene, and a video is usually 6–8 scenes. If the script wants more, look for the second concept hiding in it — it probably wants its own entry.
Should docs videos share assets with our marketing explainer? Share the visual system, not the videos. A homepage explainer argues to a stranger; a docs video explains to a user. Same layout grammar and colors is good (the product should feel like one thing), but re-cutting a marketing video into docs produces material that answers nobody's actual question.
Where do the videos go — docs pages or a channel? Both, but the docs page placement does the work. Embed each video on the page that owns its concept, above the detailed text. Video answers "what is this and how does it behave"; the text below answers everything the stuck reader needs next. A channel playlist is a mirror, not the home.
How do we decide which concepts get a video first? Aim at documented confusion, not the feature list. Support themes, docs pages with high exit rates, questions that repeat in your community — the video is there to fix a real confusion, and your gravity-center concept almost always tops that list anyway.
If you want to see what a per-concept video of your product would look like before committing to a series, send us your product's URL and judge twenty directions first.