A documentation video is reference material. Someone gets stuck mid-task, searches for the one concept blocking them, watches, and leaves. Because that is how every view happens, each video must teach exactly one concept, stand alone, match its siblings, and stay cheap to update when the product changes.
Suppose you are building a docs series for Sift, an error-triage tool. Errors stream in from an application, Sift groups the matching ones, and each group gets assigned to an engineer and eventually resolved. The series covers concepts like what a group is, how assignment works, and why a resolved group can reopen.
People arrive stuck, not curious
Nobody watches a docs series front to back. A Sift user hits a wall, say a group they resolved last week showing up again, and they come looking for the one video that unsticks them, which means every video must work for a viewer who arrived out of order:
- Every video must be watchable alone. The published order can build on itself, but each entry re-anchors its prerequisites in one line and moves on. The reopen video spends one sentence on what a group is, because the stuck viewer either knows already or needs the video that owns it.
- No "welcome back." Recaps, "in the last video we covered," and instructor re-introductions assume linear viewing that never happens. Only the series opener gets a welcome; every other video opens directly on its concept.
The series opener, if you make one, orients rather than teaches: the viewer should finish knowing what they are looking at and ready to explore, which is the same exit state an onboarding video aims for.
One concept per video, and the video owns it
Each video argues one sentence. For Sift's grouping video the sentence is "a group collects every occurrence of one error, so you triage groups instead of events," and everything on screen exists to make it feel obvious. If you cannot state a video's sentence, you have a topic, and a topic gives you no way to decide when the video is done (one idea per scene is the same rule at scene scale).
Each concept also lives in exactly one video, and neighbors defer to it by name. The assignment video touches groups constantly and never re-explains them; it says "assignment acts on a group" and trusts the grouping video to exist. When two videos half-teach the same concept, both fail, because each assumes the other covered the hard part. Ownership also makes the series findable: a video that owns one concept can carry that concept as its title, and a stuck user searches by concept.
- Write a "deliberately not taught" list for every video. The grouping video's list: assignment (has its own video), alert rules (docs page), the matching algorithm's internals (not taught anywhere in the series). Scope means named exclusions with destinations.
- Set an altitude ceiling for the whole series. Decide the deepest mechanism level any video may reach. A docs video gives the viewer enough mechanism to predict the product's behavior and stops there, so a video about Sift's matching algorithm internals gets reframed to what grouping does and when to rely on it.
A series is a curriculum, not a playlist
Viewers judge a docs series as a set, and a set with three visual styles and two voices forces them to re-learn how to watch with every entry.
- Start with the gravity center. Teach first the concept every other concept is defined in terms of. For Sift that is the group: the stream condenses into groups, assignment acts on groups, resolution closes groups, alert rules fire per group. Until the viewer has that object, nothing else attaches.
- Group entries into tracks. A track about one object runs from what it is, to what you do with it, to how it composes: grouping, then assignment and resolution, then alert rules.
- Never frame by a fixed count. "The Five Triage Actions" dates itself the moment Sift ships a sixth. Name the capability.
- Keep one visual system. Same layout grammar, same color meaning, same pacing across every entry. Sameness that would bore in a marketing reel is right in reference material, because a viewer who is not decoding the format has all their attention left for the concept.
Docs videos run short: our produced concept videos run 60 to 90 seconds, and a full eleven-module course came to about eleven minutes of animation. An entry that wants three minutes usually contains two concepts and should be split (more on runtime).
Keeping videos true as the product changes
A video showing last quarter's UI damages trust exactly where users go to find out what is true. Staleness is an economics problem, though, and you can build for it:
- Ground every on-screen value, and re-check at every build. Every label, number, and color traces to a real product source in a grounding table, and the table gets re-checked against the product on every rebuild. When the product changes, you diff a list instead of re-watching a library.
- Build per scene. When one screen changes, one scene rebuilds and the approved scenes around it stay untouched. 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. If Sift renames "resolve" to "close," the fix is a one-line edit and a re-render. In our experience wording changes are the most common way docs videos go stale, so cheap re-narration pays for itself first.
- Make "redo" a first-class state. Our plan of record marks every video as exists, redo, or new. A library with no state between "published" and "deleted" keeps stale videos live because nobody has a place to put them.
If you are commissioning docs videos, ask any vendor what one changed screen costs you. If the answer is a new project, the videos will stale out within two quarters.
When a diagram beats a video
Refusing pages is what keeps the videos you do make worth watching. We keep a standing "never animated" list per product:
- UI procedures. Click-here-then-here content belongs in a screen recording: faithful by construction, cheap to redo, pausable.
- Reference facts. Permission tables, config options, and API fields need to be scanned or searched, and video can be neither.
- Setup flows. Install steps change constantly and get read while typing, so text with copy buttons wins.
- Internals. Algorithm deep-dives serve the curious, violate the altitude ceiling, and read better as a static diagram.
What remains is anything the viewer can only understand by watching it change: errors streaming in and condensing into groups, a group's history accumulating toward an alert threshold. Animation earns the render there, and showing the real product matters most there too, because a docs viewer knows the UI and spots invented surfaces instantly.
FAQ
How long should each docs video be? 60 to 90 seconds, built as six to eight scenes of 8 to 12 seconds with one idea each. A longer script usually contains a second concept that should become its own entry.
Should docs videos share assets with our marketing explainer? Share the visual system, not the videos. A homepage explainer was built to convince a stranger who hasn't bought in yet. 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 does the work. Embed each video on the page that owns its concept, above the detailed text. A channel playlist is a mirror, not the home.
How do we decide which concepts get a video first? Aim at documented confusion: support themes, docs pages with high exit rates, questions that repeat in your community. The gravity-center concept almost always tops that list anyway.
To see this on your own product, send us the URL. Twenty short candidate videos come back, and you pick the ones worth finishing.