Explain your devtool without setting off the marketing alarm

A devtools explainer 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, developers file it as marketing and discount everything after — including the true parts.

Get 20 free videos of your product

No brief. No call. No card. Made by the team behind 20cuts.com.

Does your video trip the allergy?

Answer honestly for the cut you have. Each yes is a documented trigger.

Does the narration use suspense, drama, or aphorisms?Trailer voice — a rejected draft opened “From out here, it's already over.” The note back: this is an explainer, not marketing.

Is there a comparative you can't support? (“blazing fast”, “10x”)Developers hear an unsupported comparative as a lie or a benchmark request.

Is any value on screen not traceable to a real run?Suspiciously round latencies and timestamp-less logs quietly reclassify the video as fiction.

Does a cursor click a control that doesn't exist, or a command appear that wasn't tested as typed?A shown command is a promise that it works, flags and all.

Is any outcome staged for the camera?The worst-graded video in one review batch drew a six-word verdict: “don't see anything cool, also false.”

Does on-screen text restate what the narration says?The text-wall: a slide deck with a soundtrack.

Does the video only make sense with sound on?It'll be watched muted, in a README, scrubbed with arrow keys.

Does the product first do something interesting after second ten?The audience triages; the mechanism must be on screen immediately.

The allergy is specific

“Developers hate marketing” is too vague to act on. The reaction has named triggers: trailer voice (plain sentences that define terms beat drama, every time), uncalibrated claims (downgrade “more informed decisions” to “informed decisions” if you can't prove the “more” — it reads as confidence, because it is), and staged outcomes. And the rule that governs everything: every claim gets tested the same day. A developer who likes your video runs the install within the hour; anything the video showed that the tool doesn't do becomes a filed issue with your video linked as the reproduction.

Show the real tool — sharpened for devtools

Ground every value in a real run: the exact demo config, one real execution, the full output, the log with real durations. The standing rule is “no row, no value” — a number that can't be grounded stays off screen. Developers notice fake terminal output the way musicians notice mimed guitar.

Two more edges: a shown command is a promise — test the exact incantation before it renders. And keep code out of the voice — screen shows code, voice explains what a value means. Each channel does the job it's good at.

Why a diagram beats a talking head

For most devtools the thing being sold is invisible: a scheduler, a data flow, a retry policy. A person on camera can only describe an invisible mechanism; a diagram can run it. Viewers infer causality from timing — when a queue visibly drains as workers light up, nobody has to say “workers consume the queue.”

A worked example from an accepted scene list: to teach that a join step waits for all its inputs, the build fires two branches together, lets the fast one finish, and holds the join visibly pending while the slow branch works. The beat intent, verbatim: “the viewer should feel the wait, not be told about it.” A talking head cannot make you feel a wait.

One routing rule so “diagrammatic” doesn't overapply: animate the concept, record the live tool. Animation pretending to be a live terminal session is the fake-UI failure with extra steps.

Where it lives: README, docs, launch

README: highest traffic, hardest constraints — inline, muted, seconds to decide. ~60 seconds, mechanism on screen immediately, final frame treated as the poster that lives there after playback. Docs: calm concept explainers, one idea per video, ordered like a curriculum — and keep a standing list of topics you'll never animate (setup flows, reference tables; a recording or a page does those better). Launch: the one placement where excitement is the job — and where claim discipline holds double, because launch traffic maximizes same-day verifiers.

Questions

Can't we just record a terminal session?

For docs and proof beats, yes — and you should. But a recording only shows what's visible, and a devtool's selling point is usually the invisible part. 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, when you'd reach for it. Sound-on viewers get the full lesson; muted viewers still get the machine.

Should we mention competitors?

Show your mechanism honestly and let viewers run the comparison themselves — they will anyway, in a terminal, within the hour. A true demonstration is hard to argue with; comparison claims invite rebuttal threads.

Skip the brief. Judge the work.

Paste your product's link at 20cuts.com and get 20 short videos of it by tomorrow, free. Pick the one that lands; pay a fixed price only to finish it.

Get 20 free videos

Want the long-form version? Read the full guide: how to make a devtools explainer video on 20cuts.com.