Video vs written documentation: the decision, with evidence

Four axes decide the format, not a preference poll#

Asking whether your docs should be video or text is the wrong question, because it gets asked once for a whole documentation set when the real decision happens page by page. The usual tiebreaker, a survey where most people say they would rather watch than read, settles nothing: it measures which format people enjoy, not which one teaches a task faster or leaves a reader stranded. A better instrument is a rubric you run against each doc job, scoring four independent axes and reading the format off the total. The four are the nature of the knowledge (spatial or symbolic), how the reader consumes it (once or repeatedly), how fast the thing on screen changes, and how the reader arrives at the page. The pillar maps the whole doc surface at once; this spoke is the scorecard for a single passage, so the medium stops being a matter of taste.

Axis one: spatial knowledge versus symbolic knowledge#

The first question is what kind of knowledge the passage carries. Spatial and temporal knowledge, where a thing sits, how it moves, what changes between two states, is what prose is worst at and motion is best at. A paragraph can assert that a panel slides in when you drop a card on a lane; three seconds of video prove it, and the reader never has to guess which panel or which edge. Symbolic knowledge is the opposite: the exact name of a field, the value a flag takes, the precise wording of an error. That is what text renders exactly and video only gestures at. Software professionals feel the pull themselves. When Oliver Karras asked them directly, 59 of the 64 who answered saw video as able to sharpen how requirements get communicated, yet the same respondents did not want it everywhere, and 34 flagged real obstacles to using it at all¹. Video earns points here only when the difficulty is spatial, not conceptual.

Axis two: read once, or return a hundred times#

The second axis is consumption pattern, and it is the one teams get most wrong. Some docs are read once, while the reader builds a mental model of a thing they have never seen: a first-run tour, an unfamiliar workflow, an onboarding path. Others get hit repeatedly, mid-task, by someone who already knows what they want and needs to grab one detail and leave. Video suits the first and actively punishes the second, because it can only be taken in linearly. Amy Schade's usability work found that video defeats the skim-and-jump reading people default to on informational pages, and that it costs a reader more time than the same content set in text⁴. Someone who returns to a page forty times a month to copy the same command will not watch ninety seconds to reach second sixty-one, ever.

Axis three: how fast the thing on screen changes#

The third axis turns a good video into a liability, and it has nothing to do with the reader. Everything you film has a decay rate: the exact UI, the button labels, the API response on screen. A text step that goes stale is a small correction; a stale clip is a narrator pointing with confidence at a control that has since moved. The cruelty is that the highest-value doc videos, first-run and onboarding, sit on the fastest-changing surface, so the rot arithmetic is worst exactly where video helps most. This axis carries a veto: if the thing on screen churns and you have no way to regenerate the clip, video scores negative no matter how spatial the task is. The only escape is a video that rebuilds from a spec instead of a hand-recorded take. Our own engine, aidemo, is one take on that pattern, disclosed and honestly limited: it drives a real browser and only a browser, its storyboard is authored by an agent and corrected in text by a human, and nothing in it resembles a timeline you drag clips around in. The mechanism matters more than the tool. A high-churn surface can carry video only if the video is regenerable.

Axis four: whether the reader arrives by searching#

The last axis is the entry path. Readers who reach a page through an onboarding sequence or an in-app link arrive ready to watch. Readers who reach it by typing an exact string into a search box or a find-in-page bar hit a wall. You cannot search the pixels of a video, a reader cannot lift a command or a config value out of a playing frame, and a crawler does not read footage at all. Google is explicit that it leans on the text around a video to place it: it "recommends providing metadata," requires that the "watch page must be indexed," and asks that each page carry a "page title and description that are unique to that video"⁵. Pixels are not self-describing, to a crawler or to a reader in a hurry. A transcript recovers some of this by handing search and the impatient reader a text layer, which is why captions and a transcript belong on every doc clip, but a transcript is just text doing the findable work the footage cannot.

The scorecard, run against three real doc jobs#

Score each axis from minus two (text) to plus two (video), add the four, and read the route. Plus four or more means make it a video or a short silent clip; minus four or lower means keep it text; anything between means both, with text as the page and a clip beside the one step that needs motion. Axis three keeps its veto: a negative change-rate score with no regeneration path caps the whole total at zero.

The drag question lands at zero, which is the honest answer: a ten-second wordless loop next to written steps, the microvideo unit most docs sites actually keep. The webhook reference bottoms out at minus eight and never becomes a video; every axis pushes it to text. The onboarding job scores plus four, the textbook case for motion, but the asterisk is the whole point, because it also scores worst on change rate, so it is only a video if you can rebuild it. And for onboarding the live contest is often video against an interactive product tour rather than video against text, which turns on where the doc lives, not on this rubric.

Where text quietly, permanently wins#

Two facts keep text the default substrate no matter how the axes fall. First, people do not read documentation, they scan it: Nielsen's testing found "79 percent of our test users always scanned any new page they came across; only 16 percent read word-by-word"³. Scanning is a text affordance; footage has no shape to skim. Second, text is what everything else is built on: search indexes it, screen readers speak it, a pull request diffs it, and a reader copies from it. Video is also the harder medium to make well. Karras and Schneider are blunt that most people who would shoot these clips "are not directors" and "do not necessarily have the required skills," which is why they argue for a quality model so teams can produce "good videos at moderate costs, yet sufficient quality"². None of that says never shoot a video. It says text is the floor, and video is the addition you make when a passage scores its way onto the screen, never the reverse.

Sources#

1. Karras (2018) — Software Professionals' Attitudes towards Video as a Medium in Requirements Engineering
2. Karras and Schneider (2018) — Software Professionals are Not Directors: What Constitutes a Good Video?
3. Nielsen, Nielsen Norman Group (1997) — How Users Read on the Web
4. Schade, Nielsen Norman Group (2014) — Video Usability
5. Google Search Central — Video best practices (accessed July 2026)

FAQ#

Should documentation be video or text?#

Decide it per passage, not per project. Score the job on four axes: is the knowledge spatial or symbolic, is it read once or looked up repeatedly, how fast does the thing on screen change, and does the reader arrive by searching. Spatial, learn-once, stable, link-arrival jobs want video; symbolic, repeated, fast-changing, search-arrival jobs want text. Most pages land in between and want text with a short clip beside the step that needs motion.

Do developers prefer video or written documentation?#

For learning something unfamiliar, many welcome it: in Karras's 2018 survey, 59 of 64 software professionals said video could improve requirements communication. For reference work they reach for text every time, because they scan, search, and copy, and video allows none of the three. The preference splits by task, not by person, so a blanket "developers prefer X" claim is useless for a format decision.

Is it worth making both a video and a written version?#

Often yes, and it is less work than it sounds, because the text is not optional. A transcript next to a clip is indexable by search, skimmable by a reader in a rush, and required for accessibility, so the words earn their place three ways at once. The mistake is treating the pair as two full docs; treat the text as the page and the video as the one step that genuinely needs motion.