The first-run screen is the surface you redesign on purpose#
An onboarding walkthrough has a cruel property: it is at once the most valuable clip in your documentation and the one guaranteed to rot fastest. Valuable, because it shows a brand-new user the exact first-run interface at the one moment they have no mental model of it and the most doubt about whether to stay. Fast-rotting, because that first-run interface, the signup form, the welcome modal, the setup checklist, the empty workspace, is the surface a product team reshapes most deliberately and most often.
That churn is not an accident of the interface; it is where the growth work lives. Onboarding is "the process of guiding new users from the moment they sign up to their first meaningful experience with your product," an end-to-end journey across "in-app flows, emails, empty states, tooltips, checklists, and more"1, and every one of those touchpoints is a lever a team pulls to raise activation. A page you keep testing is a page you keep changing, so the first-run flow moves faster than the settled core of the product that a walkthrough of, say, the export screen would document. The highest-value doc video sits on the least stable ground you own. The pillar case for video as a documentation medium names maintenance, not production quality, as what closes most video programs; onboarding is where that tax is steepest.
This piece is not about what an onboarding clip should contain, the activation-first job of an onboarding video is worked out separately, sorted by the metric each type moves. It is about the narrower engineering problem underneath: how to build a first-run walkthrough that shrugs off a small UI change and re-renders cheaply for a large one, so it keeps matching today's signup flow instead of last quarter's.
Video or an in-app tour: which fits the first run#
For first-run specifically, the live competitor to a walkthrough video is not a paragraph but an in-app tour: the tooltips, modals, and checklists that overlay the running product. Appcues describes those as "lightweight, contextual onboarding elements that surface guidance exactly where users need it," with product tours that work only when "short, focused, and tied to a specific action"1. The general decision between an interactive tour and a video turns on distribution and funnel stage; the first-run slice has its own logic worth separating out, because the two formats fail in opposite directions.
An in-app tour renders on the live product, so it never shows a screen that no longer exists, but it breaks the instant a step's anchor moves, the user must already be signed in to see it at all, and it cannot be watched before signup, emailed, or pasted into a help center. A video can be watched by a prospect who has not signed up, lives in docs or a launch email, and carries a narrated argument, but it freezes the interface at record time and goes stale without a sound.
| First-run need | In-app tour (overlay) | Walkthrough video |
|---|---|---|
| Playable before signup, in docs or email | No, needs the user inside the app | Yes, a file plays anywhere |
| Reflects today's exact UI automatically | Yes, it sits on the live app | No, frozen at record time |
| Carries narration and a reason why | Weakly, a line of tooltip copy | Yes, that is its strength |
| Fails when a step moves | Anchor misfires mid-flow | Cursor points at the wrong spot |
| Interrupts the user's own task | Yes, and users skip it | No, the user chose to watch |
That last row is the one teams underweight. NN/g's onboarding research is blunt that "lengthy promotional onboarding will likely be skipped," that tutorials "didn't improve task performance," and that the right instinct is often to "avoid creating app onboarding whenever possible and instead spend your resources making the UI more usable"2. Read alongside the table, the honest split is this: use in-app tooltips for in-the-moment nudges a user can dismiss, and use a walkthrough video for the surfaces a tour cannot reach, the pre-signup evaluator, the help center, the onboarding email, kept short, since a one-to-five-minute educational clip still holds over half its viewers before engagement drops off fast3. The two are complements. The video half is the one this piece hardens against redesigns.
Narrate the outcome, not the pixel#
Here is the single authoring decision that determines whether a walkthrough survives a small UI change: what the narration is pinned to. A script written around where things sit on screen dies when they move. A script written around what the user is trying to accomplish survives, because the user's goal is the one thing a redesign is not allowed to change.
Technical-writing style guides already codify this for prose, and it transfers straight to a voice track. Google's developer documentation style guide is explicit: "Don't use directional language to orient the reader, such as above, below, or right-hand side," because such phrases "don't work well for accessibility or for localization," and it tells you to name the control by its visible label instead4. The rule that keeps a written instruction accessible keeps a spoken one durable, for the same reason: both are pinned to intent, not to the arrangement of the moment.
Rewrite each brittle line into a durable one and the pattern is plain:
| Brittle narration (pinned to the layout) | Durable narration (pinned to the outcome) | Survives which change |
|---|---|---|
| "Click the blue button in the top-right corner" | "Create your first project" | Recolor, move, and restyle all survive |
| "Open the third tab along the top" | "Go to your billing settings" | Reordered or renamed tabs survive |
| "A modal pops up in the center of the screen" | "Confirm your workspace name" | A swapped or repositioned component survives |
| "Type into the big field under the logo" | "Name your team" | A relaid-out form survives |
| "Press the hamburger icon" | "Open the main menu" | A new icon, or an added label, survives |
Every line on the right still makes sense after a recolor, a relayout, or a localization, because none of them describe the paint; they describe the job. When the narration names the outcome, a redesign that keeps the outcome, which is nearly every redesign, since one that removed "create a project" would be a different product, leaves the voice track correct even though the pixels moved. This is the spoken twin of pinning the machine's selectors to the accessibility tree rather than to nth-child position: the selector keeps the cursor landing on the right element, and outcome-based narration keeps the voice describing the right thing, and neither has to be re-authored when a designer reaches for the stylesheet. Good how-to videos are scarce partly because "software professionals ... are not directors" and skip exactly this kind of discipline5; this particular discipline is small, specific, and most of what buys durability.
What a small redesign actually breaks#
Outcome-based narration is necessary but not sufficient, because a walkthrough is three layers stacked, and a redesign hits them differently. The script is one layer. The cursor path and any zoom are a second, pinned to where the target element sits. The step sequence, the order of actions the flow demands, is a third. Sort a change by which layer it touches and you know at once whether you have a clip that still ships, a clip that needs a re-render, or a clip that needs re-authoring.
| Change a redesign makes | Narration (outcome-based) | Cursor path and zoom | Step sequence | Verdict |
|---|---|---|---|---|
| Recolor or restyle | Fine | Fine, the element stays put | Fine | Ships unchanged |
| Rename or re-icon a control | Fine, it named the goal | Fine if the selector is role-and-name | Fine | Ships, or a one-line selector edit |
| Move or relayout an element | Fine | Cursor lands wrong; needs a re-render | Fine | Re-render from the same spec |
| Reorder or add a required step | Needs a line | Needs the new target | Changed | Edit the spec, re-render |
| Remove the flow entirely | Wrong | Wrong | Gone | Re-author: the task itself changed |
The middle three rows are the whole argument for treating the walkthrough as something you re-render rather than re-shoot. A moved element or a new required field does not need a human back in a screen recorder performing the flow again; it needs the cursor pointed at the new location and the clip rebuilt, which is a spec edit and a render. Only the last row, where the task itself is gone, is genuinely new work, and that is correct, because a walkthrough of a flow that no longer exists should fail loudly rather than limp along. That is the same reason resilient targeting doubles as a way to catch UI drift before the video lies: a re-render against today's build either succeeds or tells you exactly which step broke, which is far cheaper than a viewer discovering it for you.
Closing the loop so the walkthrough shows today's signup#
Durable narration and resilient targeting buy survival against the small changes. The large ones, the quarterly signup redesign, the reworked empty state, the new required field, still demand a fresh clip, and the only model that keeps pace is regeneration: hold the walkthrough as a committed spec that a machine replays against the current build, so "the signup flow changed" and "the walkthrough is current" collapse into one event. Keeping a whole tutorial library current at scale works the arithmetic across many clips; for a single onboarding walkthrough the case is even sharper, because it sits on the fastest-moving surface, which makes it the clip most worth wiring to re-render on the commit that touched the onboarding path.
Our own engine, aidemo, is built for this loop, and it fits a docs pipeline only with its limits stated plainly: it drives a browser and nothing native, its storyboards are authored by a coding agent instead of assembled on a visual timeline, and it ships no drag-and-drop editor. It earns its place on a first-run walkthrough you mean to keep true for years, not on a throwaway screencast. The engine matters far less than the two habits the format rewards, both specific to onboarding: narrate the outcome, so a restyle leaves the voice correct, and keep the flow re-renderable, so the redesign that reshaped your signup rebuilds the video instead of quietly invalidating it.
Sources#
- Appcues — User Onboarding (definition and in-app patterns, 2026)
- Kendrick, Nielsen Norman Group (2020) — Mobile-App Onboarding: An Analysis of Components and Techniques
- Wistia — How to Choose the Right Marketing Video Length (2026)
- Google — Developer Documentation Style Guide: Accessibility (directional language)
- Karras and Schneider (2018) — Software Professionals are Not Directors: What Constitutes a Good Video?
FAQ#
Is a video or an in-app product tour better for user onboarding?#
They do different jobs, so most products need both. An in-app tour of tooltips, modals, and checklists overlays the live product, so it always reflects the current UI, but it only works once a user is signed in and inside the app, and NN/g finds users routinely skip lengthy onboarding2. A walkthrough video plays before signup, in docs, and in email, and carries narration, but it freezes the UI at record time. Use tooltips for in-the-moment nudges and a video for the surfaces a tour cannot reach.
Why does my onboarding walkthrough go out of date so quickly?#
Because it films the part of the product that changes most. The signup flow, welcome screens, and empty states are where teams run the most experiments to lift activation, so the first-run UI churns faster than the settled core. A walkthrough pinned to that surface is falsified by the very redesigns meant to improve it. The fix is to narrate outcomes rather than pixel positions so small changes do not break it, and to re-render from a committed spec when a large change does.
How do you write onboarding narration that survives a UI change?#
Name what the user is accomplishing, not where the control sits. "Create your first project" survives a recolor, a relayout, and a rename; "click the blue button in the top-right corner" breaks on all three. This is the same rule Google's developer style guide gives for written docs: avoid directional language like "above" or "right-hand side" because it fails for accessibility and localization, and refer to a control by its visible label instead4.
