Technical
Technical documentation to video, without a screen recording
Every docs team has a video showing a UI from two redesigns ago. The fix is making the video a build artefact rather than a recording.
Why docs videos rot faster than docs
Documentation is maintained because editing a page is cheap. A video of the same content is not maintained, because editing it means re-recording — so the docs stay current and the video drifts until someone notices it shows a button that no longer exists.
The result is worse than having no video: a stale walkthrough actively misleads, and users trust it because it is official.
Make the video a build artefact
The way out is to stop treating the video as a recording and start treating it as something generated from the docs, the same way the docs site is generated from Markdown.
When a page changes, the video for that page regenerates. Nobody re-records, nobody schedules studio time, and the video cannot drift further than the last build. This is the whole argument, and it is why a synthesised narration track is worth more here than a human one — a human voice makes the artefact unregenerable.
- Source of truth stays the docs page, not a script file.
- Narration is synthesised, so regeneration is free.
- Version the video alongside the docs version.
- Regenerate on release, not on request.
Code on screen: the specific problem
Technical content has a constraint most document types do not. A code block that fits comfortably in a docs page is unreadable as video, because docs are read at arm's length on a wide screen and video is watched on a phone.
The working limits are roughly twelve lines and sixty characters. Past that, either split the block across scenes or show only the lines that changed with the surrounding context dimmed. Never shrink the font to fit — an illegible code block is worse than a described one.
What documentation video is good for
Not reference material. Nobody watches a video to look up a parameter, and turning your API reference into video is a waste of both formats.
It works for the conceptual pages — the architecture overview, the 'how this fits together', the getting-started narrative. These are the pages people read once, are the hardest to write, and are where a five-minute explanation genuinely beats a page of prose.
The interactive exception
Where the thing being explained is genuinely interactive — a debugger session, a dashboard, a multi-step console flow — record it. A generated video cannot show a UI responding, and pretending otherwise produces a worse artefact than a slightly stale recording.
The hybrid most docs teams land on: generate the conceptual sections from the docs, record the interactive ones, and accept that the recorded parts need a maintenance calendar.
Frequently Asked Questions
Which docs pages are worth turning into video?
Conceptual and getting-started pages. Reference material is not — people arrive at a reference page looking for one parameter, and video is the worst possible format for lookup.
How much code can be on screen at once?
About twelve lines at sixty characters, readable on a phone. Beyond that, split across scenes or highlight only the changed lines.
Should documentation videos be versioned?
Yes, alongside the docs version they were generated from. A user on v2 following a v3 video is the failure this whole approach exists to prevent.