Every product video says a handful of true things: what the product is, why it matters,
the proof, and what to do next. This guide gets them out of whatever the person has,
in their own words and order, into one file, source/facts.md, that the script is
written from (llm-write-an-ad-script, guide-make-a-script-from-source). Nothing goes
on screen or into the narration that isn't in it.
First question: what do you have? Ask it plainly, and take everything they have:
a website, a GitHub repo, the product running on this computer, docs or a help page, a
details doc or brief, an earlier launch video. Several sources are common (a site plus
the app to screenshot); read each by its route and merge them into one facts.md.
Routes
| Source | Pick it when | Cost and time | What you get | Load |
|---|---|---|---|---|
| A website | The product has a homepage or product page | Free, minutes in the browser | The headline, sub, value props in page order, the CTA's words, the numbers the site shows | references/read-a-site.md; images and logo via guide-capture-a-brand |
| A GitHub repo | The product is code (a CLI, a library, an app's own repo) | Free, five API requests | The exact name, install command, named parts, what shipped lately, where the marketing images live | references/read-a-repo.md |
| The product on this computer | It runs here (a desktop app, a web app on a local or staging address) and the screens are the story | Free | Full-resolution screenshots of the key screens, the UI's own words for each step | Screenshots, below (a desktop app: macOS only) |
| Docs or a help page | The video is about one feature or how to use it | Free | The feature's exact name, its kinds or routes, defaults, prices and limits, the one thing the viewer must do | Read the page and what it links |
| A details doc or brief | The person wrote down what to say (prices, offer, audience) | Free | Their facts, their emphasis | Read it; ask for anything missing |
| An existing launch video | The brand already made one | Free | Its beats and their lengths, full-resolution frames of its real screens and logos | ffmpeg-scene-cuts or a 1 fps sheet (python-contact-sheet) |
Process
- Ask what they have, and who the video is for (a cold social viewer, a customer, an
investor). Save every source in
source/, never edited. - Read each source by its route. Save what you read:
source/site_copy.md,source/repo/,source/screens/, the page or doc itself. - Write
source/facts.md(the shape below). Keep the substantive points and their source order as evidence. Select the points that serve this video's audience, purpose and length; the script need not cover every site section or follow page order. Preserve any coverage or ordering the person's brief requires. - Check the brief against it. Every claim in the person's brief (or in your own
draft later) gets a line in
facts.mdor a question back. Briefs go stale: a feature a brief called "coming soon" had shipped months before, in the repo's release notes. - Gate, often joined with the next one: show
facts.mdwith the points you propose to use, in order, and any conflicts between the brief and the source.
source/facts.md
# <Product> facts (read <date> from <sources>)
Headline: <the source's own, verbatim>
Sub: <verbatim>
For: <who it's for, in the source's words>
Value props, in the source's order:
1. <prop, in its own words> (<where: H2 on the homepage>)
2. ...
Numbers:
- "<2 million households>" (<homepage, "Over 2 million households" heading>, read <date>)
Named parts, verbatim: <commands, modules, plans, feature names, with their casing>
Integrations, as the brand shows them: <names, and where it shows them>
CTA: "<the button's exact words>" -> <where it goes>
The one thing the viewer must do: <install command, sign up, book a demo>
Not to say: <claims the source doesn't support; anything the person ruled out>
Screenshots of the running product
Ask which flow to show (the first five minutes of a new user, the one feature the video is about), then capture each screen in it at full resolution:
-
A web app: open it in your browser at a desktop size and take each screen. Ask for a demo account or seed data, never the person's real customers.
-
A desktop app, on a Mac: bring it to the front and capture the display with macOS's
screencapture, then crop the window out (a Retina display captures at 2× its points, e.g. 6016×3384).execrefusesscreencapture(it runs only ffmpeg, ffprobe, the programs hn4a installs, Python and.pyscripts), so run it from your own shell:screencapture -x -t png source/screens/01_home_full.pngWith no shell of your own, run it from Python through
exec(references/capture-screen.md). If the capture shows only the desktop, the app the command runs under needs Screen Recording permission in System Settings; ask the person to grant it, never change it yourself. On Windows or Linux, ask the person for the screenshots. -
Clean state on every screen: no notifications, dev toolbars, personal names or emails, real customer data or half-loaded spinners. Note each screen's own words (menu items, button labels) verbatim in
facts.md: they are the named parts. -
Sheet the screens (
python-contact-sheet,images) and look at every one.
Choosing
- The source's order is the brand's ranking. Keep value props in the order the site or doc gives them; reorder only with the person.
- Numbers carry their line and date, and round down. "Over 2 million" for 2.3 million, never "2.5 million". A count from a repo (stars, modules) is dated: it changes daily.
- Named parts verbatim, with the source's casing (
lint-fix, Acme Lists, not "Acme lists"). A video that says "whatever language you ship" instead of naming them lost the product's substance. - Integrations only as the brand shows them: the names it lists, and logos only
where it shows logos (
guide-capture-a-brand, Avoid). - The repo, not just the README: the README can lag the code by months; release notes and the commit log of the area the pitch is about say what shipped.
- A help page is read whole, with what it links that carries the feature (routes, defaults, prices, limits).
- A details doc's prices are the only prices. Never invent or estimate one; ask.
Avoid
- Writing the script before
facts.mdexists: invented reviews, numbers and claims start there. - Submitting a site's lead form, signing in, or downloading a video to get more: a thumbnail and the public copy are usually enough; ask first.
- Copying a competitor's claims or a review site's numbers as the brand's own.
- Screenshots with a real person's data in them.
Related
guide-capture-a-brand: the look, the images and the logo from the same sources.llm-write-an-ad-script,guide-make-a-script-from-source: what is written fromfacts.md.
