One of the stranger product problems I have worked on involved an onboarding flow that was not broken.

Every screen worked.

The buttons worked. The setup steps were still technically valid. A new customer could follow the flow and connect an application successfully.

And yet the experience had become wrong.

The reason was simple: the product had changed faster than the onboarding.

The first version assumed one primary way of connecting an application. Over time, more paths became possible: different languages, existing observability systems, gateways, platforms, and environments where writing application code was not necessarily the starting point.

The natural response was to add those new options to the existing screen.

I started there too, but it quickly felt like we were decorating an old assumption. The real issue was not the number of integrations. It was that the onboarding was mixing two different concepts.

The customer had an application they wanted to understand. We had several ways to obtain information about that application.

Those are not the same thing.

Once I separated them, the flow became easier to reason about. Instead of asking the customer to navigate our integration inventory, the experience could begin with their environment and guide them toward the appropriate connection method.

There was another subtle problem.

If a product shows only a handful of connection paths on the first screen, customers can easily interpret those examples as the boundary of what the product supports. The UI may be trying to simplify the experience while accidentally narrowing the perceived product.

That is why I have become careful about “simple” onboarding.

Simplicity is not the same as showing fewer things. A screen with three choices can still create more confusion than one with six if the first three are organized around the wrong mental model.

This also changed how I review mature product surfaces.

When a screen feels awkward, I try not to immediately move components around. Sometimes the layout is fine. The problem is that the objects on the screen belonged to an earlier version of the product.

A redesign can therefore fail even when it looks much better.

The new design may preserve the same outdated structure with nicer spacing.

The interface is often the last place where an old product model remains visible.

That makes onboarding especially useful. It forces the product to explain itself from the beginning.

If that explanation is becoming difficult, the problem may be deeper than the onboarding.