What 800 software videos taught me about onboarding

To record a tutorial I have to arrive at a product the way a new user does: a fresh account, no data, no context, and a script that has to reach something worth watching before the viewer leaves. I have done that more than 800 times since 2019, across more than 200 brands.

That is an unusual seat. A product team cannot occupy it. They have known their own software too long, and no amount of user research gives back the experience of not understanding it. I get handed that experience once per product, and then I lose it too — the second recording is never as revealing as the first.

So I started keeping notes on where the first run breaks. The same patterns keep coming back.

The empty state that assumes data

The most common failure is a first screen designed for a populated account. Charts with no numbers, a table with a header row and nothing under it, filters over an empty set. The interface is technically correct and completely uninformative.

The products that handle this well do one of two things: they seed a realistic example the user can poke at and then delete, or they replace the whole screen with the single next action. What almost nobody does is the middle option — a dashboard with a polite message telling you it will be useful later. That version teaches nothing and gets ignored.

The tour that fires before the value

Product tours are usually triggered on first login, which is the moment the user has the least reason to care. Five tooltips explaining a toolbar for a job they have not started yet. I skip them on camera, every time, and then have to go find the features manually anyway.

The tours that work are the ones attached to a moment of need — the first time you land on an empty project, the first time a record has more fields than fit on screen. Timing is doing more work there than content.

Settings before showing

A surprising number of products open with configuration. Choose your workspace type, invite your team, connect a data source, pick a plan. Each screen is defensible on its own and together they ask for a lot of commitment from someone who has not yet seen the thing work.

When I script these, the video is long and the retention is bad, and both facts have the same cause: nothing has happened yet. The strongest first runs I have recorded put something on screen the user did not have five minutes ago, and ask for the setup afterwards.

Terminology that drifts across surfaces

This one is invisible from inside a company and glaring from outside it. The marketing page says workspace, the interface says project, the documentation says environment, and the API calls it a tenant. All four are the same object.

It is not fatal, but it costs the user real effort. Every time the word changes, they have to check whether the concept changed too. I notice it because a script has to pick one word and stay with it, and I cannot do that without deciding which of the four is correct — a decision that should not be mine.

The pricing page that hides the unit

I get asked about pricing in the comments of nearly every video, which means most pricing pages are not answering the question. The failure is almost always the same: the tiers are clear and the unit is not. Per seat, per what — an active seat, an invited seat, a seat that logged in once last quarter? Usage-based, metered against which event?

A tier list without a defined unit is not a price. Teams that state the unit plainly get fewer support questions and, from what I can tell, more trust.

What the good ones have in common

Across 200 products, the ones that were easy to explain shared something simple: they had a clear idea of the first useful thing a person could do, and the entire first session was arranged around getting there.

That is harder than it sounds, because it requires a decision. Most onboarding that goes wrong goes wrong from trying to serve every user path at once — the evaluator, the admin, the end user, the person who arrived from a comparison article — and refusing to pick a default. The result serves nobody in particular.

The tell I now use

Here is the practical signal I have ended up trusting: if the script gets long before anything happens on screen, the onboarding has a problem.

I do not decide that in advance. It emerges from writing. When I have to spend ninety seconds explaining concepts before the first click produces a visible result, the product is asking the user to build a mental model before giving them a reason to. Sometimes that is unavoidable — genuinely complex tools are genuinely complex. More often the complexity was arranged in the wrong order, and the same concepts explain themselves in twenty seconds once the user has seen one thing work.

The videos where I have this problem are always the videos that take longest to edit. The connection is not a coincidence. Editing is where you find out how much of what you said was necessary.

Why I am not neutral about this

I build software too, which means I have made every one of these mistakes in my own products. The empty state one twice. Watching it happen from the outside 200 times did not prevent it — but it did shorten the time between shipping the mistake and recognising it, which is most of what experience is.