Blog/Craft

Docs videos: when video beats a page

Text wins for reference and commands. Video wins for setup flows, debugging and anything visual. How to tell, and how to embed it.

Kevin Blanco··5 min read·Activation

The short answer

Put video in docs where text struggles: setup flows with many screens, debugging, visual tools, and anything where order and timing matter. Leave reference material, parameters and copy-paste commands as text. Embed the video on the page, keep the written steps beside it, and add chapters and a transcript.

01

Text and video do different jobs

Developers scan docs. They want a parameter name, a command to copy, a table to check. Text does that better than any video.

Some pages ask for something text can't give: seeing where to click, watching a failure unfold, following a sequence of screens. Those are the pages where video earns its place.

FigureWhich side a page falls on. Our rule of thumb.

02

Four questions for a page

The test

Does this page need a video?

Tick every question you answer yes to for one docs page.

Leave it as text

0 / 5

Make the text clearer. A video here would add maintenance and not much else.

03

How to embed it

  • 01

    On the page

    Embed it where the task starts. A link sends readers away and some don't come back.

  • 02

    Text beside it

    Keep the written steps. Readers who prefer text, and search engines, still need them.

  • 03

    Chapters and a transcript

    Chapters let people jump to their step. The transcript makes the video searchable.

  • 04

    One task, kept short

    A docs video shows one task. If it grows, split it.

04

Keeping it current

A video of a screen goes stale when the screen changes. Before you add one, decide who will check it with each release.

Put the date and the version it was recorded for in the description. When the product changes, you can tell at a glance whether the video still holds.

FAQ

Questions people ask

When should documentation include a video?

When the task is visual, order or timing matters, or readers get stuck. Setup flows, debugging and visual tools suit video; reference material and copy-paste commands don't.

Should I replace written docs with video?

No. Keep the written steps beside the video. Some readers prefer text, and written steps are easier to search, update and copy from.

How long should a docs video be?

As short as the task allows, covering one task. Add chapters if it runs past a few minutes.

How do I keep docs videos up to date?

Note the version and date, name an owner, and check the video whenever the screen it shows changes.

Do videos help docs SEO?

An embedded video with a transcript gives the page more text to match and keeps readers on the page longer. It adds to the written steps and doesn't replace them.

DevReel

How we do it at DevReel

We start from where readers get stuck in the docs, usually from support questions, and make a short video for those pages. Each one sits beside the text, with chapters and a transcript.

Cloudinary's videos usually average around 400 views. Ours passed 9,000 in the first week. For ngrok, watch hours tripled and subscribers went from about 450 to over 800 in the first week.

Cloudinary views

9,000+

in the first week, against a usual ~400

ngrok watch hours

3×

subscribers from ~450 to 800+ in the first week

Now the hard part

Tell us which docs pages cause the most questions. We'll tell you which deserve a video.

Kevin Blanco founded DevReel. He has made 500+ developer-tool videos and spoken at 80+ developer conferences.

Keep reading