The evidence for video in docs is narrower than the enthusiasm#
The pitch for video documentation almost always opens with a preference statistic: some large share of people say they would rather watch than read. It is a real number and a weak argument, because it measures what people claim to enjoy, not which format teaches a task faster or leaves a reader stranded at the wrong moment. The same usability researchers who study video are quick to add that "not everyone enjoys watching videos" for learning, and that some readers cannot play audio at all. Documentation is not entertainment, and a medium that half your audience skips is not a default. The question worth answering is narrower: for which documentation jobs does a moving picture measurably beat a paragraph, and for which does it quietly lose.
The software-engineering research is more careful than the marketing. When Oliver Karras surveyed software professionals on video as a documentation medium, 64 of 106 responded, and their attitude was positive but qualified: 59 believed video could improve how requirements get communicated, while 34 named real threats to using it1. A companion paper is blunter about why that potential goes unrealized: "videos are one of the best documentation options for a rich and effective communication," yet the people who need to make them "are not directors" and lack the production skill2. Video is welcome in docs and chronically under-produced, which is a different situation entirely from video being the obvious default.
Nielsen Norman Group's usability testing lands in the same place from the reader's side: video helps, as long as it never becomes the only way in. This pillar is the routing map for that judgment. The head-to-head decision between video and written documentation gets a spoke of its own; here is the whole doc surface at once.
What a moving picture proves that a paragraph only asserts#
Some documentation jobs are spatial, temporal, or unfamiliar, and those are exactly where prose strains. A paragraph can tell you a panel slides in from the right when you drag a card onto a swimlane; a three-second clip shows it, and you never wonder which panel or which edge. NN/g's instructional-video research watched users reach for video on this kind of task specifically, complex, multistep, or unfamiliar work, as reading fatigue set in, one participant saying plainly, "This is too many words ... it's video time"3. Help Scout's knowledge-base guidance draws the same boundary for support content: reach for video when the thing is "easier to show than to describe" and the underlying UI "changes infrequently"5.
Three jobs sit squarely in video's column. First-run and onboarding, where the reader has no mental model of the interface yet and a written tour reads as a list of nouns they cannot place. Anything motion-dependent, where the whole point is the transition: the drag, the reveal, the state before and after a click. And any task whose difficulty is spatial rather than conceptual: which of nine toolbar icons, in what order, with the cursor landing where. For those, the craft of the walkthrough itself, one task followed from start to finish and scripted before it is recorded, is the work. What video adds over a screenshot is time: it carries the sequence, not a frozen slice of it.
Developer documentation adds a fourth job. Teaching an API or a command-line tool often means showing three surfaces moving in concert, a terminal, an editor, and the browser result, and no paragraph reconstructs that choreography as quickly as watching it run once. That has its own capture problem, worked through in developer-education screencasts, but the underlying reason it works is the one Karras's respondents named: for rich, multi-surface communication a well-made video carries more per second than prose can, provided someone competent actually makes it.
What a paragraph proves that a moving picture buries#
The other column is larger than the enthusiasts admit. Amy Schade's NN/g work names the structural cost exactly: videos "force users to access the content sequentially" and "don't support rapid scanning for information," which is why they "require more of users' time than an equivalent piece of text"4. A reader looking up the fourth field in a config block does not want to watch ninety seconds to reach the eleven she needs. She wants to find the field name, copy the value, and leave.
Everything a text layer gives you for free, a video withholds. You cannot search inside a frame, so the reference someone reaches for under deadline is invisible to their browser's find command. You cannot copy a command out of a pixel, so a quickstart that only plays the terminal makes the viewer retype it by eye, and retyping is where the typos come from. You cannot diff two versions of a video in a pull request the way you can diff two paragraphs, so a reviewer cannot see what a doc change actually changed, and a doc that resists review is a doc that drifts. And a search engine indexes the words on a page, not the frames of an MP4, so a video with no transcript is documentation your own users cannot search their way to. Reference tables, configuration options, error-message catalogs, and anything a reader hits mid-task already knowing the exact string they are hunting all stay text, and read better for it.
Routing each doc job to its format#
Decide not "video or text" per page but per documentation type. The Diataxis framework splits docs into four needs, tutorials, how-to guides, reference, and explanation, along an axis its authors frame as the difference between a user "at study" and a user "at work"6. Lay format over that axis and the routing falls out: the action-oriented, learning-heavy corners take motion well; the lookup corners refuse it.
| Documentation job | Diataxis type | Default format | Why |
|---|---|---|---|
| First-run and getting started | Tutorial (at study) | Narrated 60-90s walkthrough | Unfamiliar and spatial; the reader has no map of the UI yet |
| One discrete task ("how do I export?") | How-to guide | 10-20s silent microvideo, text steps beside it | A single action, shown once, with the words left searchable |
| Reference: API fields, flags, config | Reference (at work) | Text, always | Pure lookup that must stay scannable, copyable, diffable |
| Concept, why it works this way | Explanation | Text, optional diagram | Re-read and cross-referenced; there is nothing to move |
| Changelog and release notes | cross-cutting | 20-30s clip plus written detail | Show the new UI once, let text carry the specifics |
| Troubleshooting an error | How-to guide | Text first, clip only if spatial | Users arrive mid-panic and search for the exact message |
One surface deserves a warning of its own. API and SDK quickstarts are the fastest-rotting video you can shoot, because a renamed field or a changed response breaks the clip silently while the written reference beside it still reads fine, which is the case for making an API-docs video regenerate from the same fixtures the docs are tested against. The rule that saves you is the same one across every row: a video shows the shape of a thing, and text carries the parts a reader has to copy, search, or trust exactly.
The unit that survives contact with a real docs site is smaller than a full tutorial. A library of short, single-action microvideos, the ten-second silent clip that stands in for one paragraph, is both more useful and more maintainable than a handful of ten-minute screencasts, and NN/g's own guidance is to split one long video into per-step clips so viewers jump straight to the moment they need instead of scrubbing for it3. For onboarding, the live choice is often not video versus text but video versus an interactive product tour; when each of those wins turns on where the doc lives and whether the reader wants to watch or to click. In a help center the bar is narrower still: a knowledge-base video only pays for itself when it deflects a ticket, which the long, unscannable ones never do.
The maintenance tax that closes most video libraries#
The failure that sinks doc-video programs is not production quality. The highest-value doc videos show the exact first-run interface, which is precisely the surface a product reshapes most often. A first-run walkthrough is the fastest-rotting artifact you can make: every tweak to the signup flow falsifies it frame by frame.
The arithmetic is unforgiving, and it is worked out surface by surface elsewhere. A disciplined SaaS still changes something a user can see once or twice a week, which puts a typical walkthrough's half-life near two months between redesigns and at a single unannounced date when a redesign lands. Now multiply by a library. Two hundred tutorials against one navigation refresh is a re-record backlog no docs team gets funded to clear, which is why keeping a tutorial library current at scale is the true ceiling on how much video a team should own. A stale text step is a small lie a reader routes around; a stale video is a lie in motion, cursor and narration pointing with confidence at a button that moved.
The only maintenance model that outlasts ship velocity is regeneration. If the flow is a committed spec instead of a hand-captured take, a machine can replay it against today's build and emit a current video. A coding agent can even write that spec by exploring the app first, so the re-render rides the same release that changed the UI, and the general case for regenerating demos rather than re-recording them transfers to docs without a change. Our own engine, aidemo, is one instance of that pattern, disclosed as ours and honestly bounded: it captures a browser and nothing else, an agent writes the storyboard while a person edits text rather than nudging clips, and there is no drag-and-drop editor anywhere in the loop. The tool is not the point. The point is that a video library stays honest only if its videos rebuild from source, exactly as the rest of your docs already do.
Making a doc video earn its keep#
Once a job genuinely wants video, a short checklist separates a clip that documents from one that merely exists.
Pair every video with text. NN/g's conclusion after years of testing is flat: video "must supplement, never replace" the written version, and users "resent" pages where a video is the sole route to an answer4. A transcript does triple duty. It satisfies accessibility, it hands search the words the MP4 hides, and it lets a hurried reader skip watching altogether. Captions are not optional either; the captioning mechanics for muted, accessible playback are a solved problem rather than a nicety. Keep each clip to one action, and show its duration up front so a reader can price the time cost before committing to it. When the loop is genuinely tiny and wordless, a GIF can beat a video, and the encoding and stable-embed tricks behind a README GIF that updates itself carry straight onto a docs page. Above all, author the video the way you author the docs around it: scripted, scoped to one job, and rebuildable when the product moves. A doc video is documentation first and a video second.
Sources#
- Karras (2018) — Software Professionals' Attitudes towards Video as a Medium in Requirements Engineering
- Karras and Schneider (2018) — Software Professionals are Not Directors: What Constitutes a Good Video?
- Harley, Nielsen Norman Group (2020) — Videos as Instructional Content: User Behaviors and UX Guidelines
- Schade, Nielsen Norman Group (2014) — Video Usability
- Stoss, Help Scout (2025) — Creating Knowledge Base Videos: Tips, Tools, and Examples
- Diataxis — A systematic framework for technical documentation
FAQ#
When is a video the right format for documentation?#
When the thing you are documenting is spatial, motion-dependent, or unfamiliar: first-run onboarding, a drag-and-drop interaction, a multistep flow a newcomer cannot picture from words. NN/g's testing found users reach for video on exactly these complex, unfamiliar tasks. When the job is lookup instead, a config value, an API field, an error string, text wins, because the reader needs to scan, search, and copy, none of which a video allows.
Is video documentation bad for SEO and search?#
On its own, yes. Search engines index the words on a page, not the pixels in a video, and readers cannot search inside a frame, so a video with no text is documentation people struggle to find. The fix is a transcript beside every clip: it gives search something to index, satisfies accessibility, and lets a hurried reader jump to the one step they need. Treat the transcript as part of the doc, not an afterthought.
How many documentation videos should a small team maintain?#
As few as genuinely need motion, because each one is a maintenance liability. The highest-value doc videos show the first-run UI, which is the part of a product that changes most, so a large library rots faster than a small team can re-record. Keep video for the handful of jobs where showing beats telling, keep everything else in text, and make the videos you do keep regenerate from a spec so they rebuild when the product ships.
