Devtools explainer videos: how to explain a developer tool without setting off the marketing alarm

An explainer for a developer tool only works if it behaves like documentation with better staging: the real tool, real output, calibrated claims, one mechanism made visible. The moment it behaves like an ad — dramatic voiceover, invented screens, a staged win — developers file it as marketing and discount everything that comes after, including the true parts.

This audience is worth the extra discipline, because the payoff is unusual: developers actually share videos that teach them something. A good devtools explainer gets pasted into Slack threads and linked from other people's docs. A bad one gets quoted sarcastically. There's not much middle.

The allergy is specific — know the triggers

"Developers hate marketing" is too vague to act on. The reaction has specific triggers, and we've hit most of them in review before learning to name them.

Trailer voice. Suspense fragments, personified machinery, punchline aphorisms. An early narration draft of ours opened a logging video with "From out here, it's already over." The rejection was blunt: this is an explainer, not marketing. The rewrite that shipped: "Every time a workflow runs, the platform records exactly what happened. That record is called a log." Plain sentences that define terms beat drama every time — and with developers, drama doesn't just bore, it signals that the substance is thin.

Uncalibrated claims. "Blazing fast." "10x your productivity." A developer hears an unsupported comparative as either a lie or a benchmark request. The discipline we hold narration to: no comparative you can't support — downgrade "more informed decisions" to "informed decisions" if you can't prove the "more." It reads as confidence, because it is.

Staged outcomes. The worst-graded video in one of our review batches showed a system catching and fixing its own failure — except the failure had been arranged for the camera. The verdict was six words: "don't see anything cool, also false." A general audience senses staging; a developer audience verifies it. Which leads to the rule that governs everything else:

Every claim gets tested the same day. A developer who likes your video runs npm install within the hour. Anything the video showed that the tool doesn't do is now a filed issue with your video linked as the reproduction. No other audience closes the loop this fast.

Show the real tool — the doctrine, applied to devtools

The general rule for any product video is show the real product. For devtools it gets sharper in three ways.

Ground every value in a real run. Before scripting, someone operates the live tool: the exact demo config, one real run, the full real output, the log with real durations. Every string, number, and label on screen traces back to that artifact — our rule is "no row, no value," and a value that can't be grounded stays off screen. Developers notice fake terminal output the way musicians notice mimed guitar. A latency number that's suspiciously round, a log line with no timestamp, a stack trace that doesn't match the language — each one quietly reclassifies your video as fiction.

A shown command is a promise. In an animated explainer, chrome may move on its own — panels docking, surfaces sliding in — because that reads as the film directing attention. But a cursor may only click controls that exist, and for devtools the equivalent is stricter: a command shown on screen is a claim that it works as typed, flags and all. Test the exact incantation before it renders.

Keep code out of the voice. Real code belongs on screen; it never belongs in the narration. The voice says "loop dot results," never backticked syntax, and it says what a value means while the picture shows what it is. Screen shows code, voice explains — the reader-facing channel and the listener-facing channel each doing the job they're good at.

Why diagrammatic beats talking-head for technical products

For most devtools, the thing being sold is invisible: a scheduler, a data flow, a caching layer, a retry policy. A person on camera can only describe an invisible mechanism. A diagram can run it.

This is a real difference in what the viewer's brain gets to do. Viewers infer causality from timing — when a queue visibly drains as workers light up, no one has to say "workers consume the queue." One worked example from our own scene lists: to teach that a join step waits for all its inputs, the accepted build fires two branches together, lets the fast one finish, and holds the join visibly pending while the slow branch keeps working. The beat intent, verbatim from the script: "the viewer should feel the wait, not be told about it." A talking head cannot make you feel a wait. A diagram with honest timing can.

Diagrammatic also survives the way developers actually watch: muted, embedded in a README or a docs page, scrubbed with the arrow keys. A talking-head video with the sound off is a silent person gesturing. A well-built diagram with the sound off still shows the mechanism, because the picture was authored first and the words were written to it.

The one place a face earns its slot: a short intro — 25 to 30 seconds, 70-odd words — where a founder states plainly what the video covers and hands off. Frame, then get out of the way. The intro never repeats a line the video itself says.

One more routing rule so "diagrammatic" doesn't get overapplied: animate the concept, record the live tool. The architecture, the data flow, the concurrency story — animation, built from real surfaces. The "run it and watch" beat — actual screen capture of the actual tool. Animation pretending to be a live terminal session is the fake-UI failure with extra steps.

Where the video lives: README, docs, launch

The README. The highest-traffic placement most devtools have, and the most constrained: viewed inline, almost always muted, by someone deciding in seconds whether to keep reading. Keep it around 60 seconds, put the mechanism on screen immediately, and treat the final frame as a poster — it's what sits in the README after playback ends, so it should hold the one image you want remembered. Everything in this placement leans on the muted-survival property above. (Open-source projects have their own norms here — covered in open-source project videos.)

The docs. Concept explainers: calm, diagrammatic, one idea per video, each video owning its concept and deferring its neighbors. Order them like a curriculum — teach the concept every other concept is defined in terms of first. And keep a standing list of topics you will never animate: setup flows, editor walkthroughs, reference tables. For those, a screen recording or a plain docs page does the job better, and the discipline of naming the exclusions is what keeps a video series coherent. The full breakdown is in documentation videos.

The launch. Launch day is the one placement where excitement is the job — the machine running end to end, framed as a real outcome, intercut with live capture. The claims discipline holds double here, because launch traffic includes the maximum density of people who will try to falsify the video within the hour. Hook fast, show the real thing, end on the strongest true frame. We wrote up the launch-specific craft in Product Hunt launch videos.

Realistic outcomes

A devtools explainer will not make anyone adopt a tool. Adoption happens in the terminal. What the video does is compress the "what is this and why would I care" phase from ten minutes of doc-skimming to ninety seconds — and for a tool whose value lives in an invisible mechanism, that compression is often the difference between a developer trying it and bouncing.

Expect partial viewing, expect muted viewing, expect the video to be judged by its first ten seconds and its most screenshot-able frame. And expect the audience to fact-check it. That last one is the constraint that, honored fully, becomes the advantage: a video that shows the real tool doing a real thing with real output is rare enough in this category that it reads as a statement about the team that made it.

FAQ

Can't we just record a terminal session? For docs and proof beats — yes, and you should. But a recording can only show what's visible, and your tool's selling point is probably the invisible part: what happens between the command and the output. Record the session, animate the mechanism, intercut them.

Do we need narration if developers watch muted? Build the picture to carry the mechanism without sound, then add narration for the why — the naming, the caveats, the "when you'd reach for this." Viewers with sound get the full lesson; viewers without still get the machine.

How technical is too technical? Go deep enough that the tool's behavior becomes predictable, and stop before the internals lecture — unless the internals are the product, in which case that's your video. The test: does this detail change what the viewer would do with the tool? If not, it's a docs page.

Should we mention competitors? Show your mechanism honestly and let viewers do the comparison themselves — they will anyway, in a terminal, within the hour. Comparison claims age badly and invite rebuttal threads; a true demonstration is hard to argue with.

If you'd rather judge than brief: send us your tool's URL and review twenty candidate directions built from your real product.