I've spent twenty years building and scaling platforms across financial services technology. In that time I've seen internal developer platforms succeed and I've seen them fail. The technical differences between the successes and the failures are smaller than you'd expect.

The organisational differences are enormous.

The adoption problem nobody talks about

Most IDP failures share a common characteristic: the platform team
treated adoption as inevitable rather than earned.

The assumption goes like this, if we build something genuinely better
than what exists, developers will naturally migrate to it. This is
rarely true. Developers are busy, sceptical of platform initiatives
based on past experience, and rational about where they invest their
time.

The teams that get adoption right treat the platform as a product with a go-to-market problem. They identify a first team, make that team successful, and let word of mouth do the rest.

The metrics that actually matter

The industry has converged on DORA metrics as the standard for
measuring engineering performance. They're useful and worth tracking.
But they measure outputs, not platform health.

A platform can have strong DORA metrics and still be quietly failing.

The metrics I've come to care about most:

Time to first deployment for a new team. Not a team that's been
on the platform for two years — a new team starting fresh. If this
is measured in days rather than hours, the platform has an onboarding
problem that deployment frequency won't reveal.

Unplanned dependency rate. How often do developers go outside the
platform to get something done? Every workaround is a product signal.

Platform team toil ratio. What percentage of time is reactive
versus proactive? If this isn't improving quarter on quarter, the
platform is treading water.

Developer NPS. Uncomfortable to measure. Impossible to argue with.

The documentation trap

Platform teams that rely on documentation to drive adoption have
already lost.

If developers need to read three Confluence pages to understand how
to deploy a service on your platform, the platform has a usability
problem. The documentation is papering over the gap between what the
platform is and what it should be.

When I hear a platform team say "we need better documentation," I now
ask a different question: what specifically are developers confused
about, and why does the platform not make that thing obvious?

The answer to that question is a product improvement. Not a new
Confluence page.

Where this comes from

These are some of the themes I explore in depth in
The Comprehensive Guide to Platform Engineering a 550-page practitioner reference I've just published covering the full platform engineering lifecycle, from Kubernetes and GitOps through to IDPs, AI-native infrastructure, and the organisational change required to make any of it stick.

Happy to discuss any of this in the comments, I'm particularly interested in what others are seeing around IDP adoption in practice.