Table of Contents
- The Mandated Platform Nobody Uses
- Product, Not Project
- Golden Paths Beat Guardrails
- The Abstraction Leak Problem
- What Developers Actually Want
- Measuring a Platform Honestly
- Build Order That Works
- When Not to Build a Platform
- Common Pitfalls
- Conclusion
- Frequently Asked Questions
Key takeaway: A platform is a product whose users can leave. If using it is slower or more constraining than the alternative, teams will route around it regardless of any mandate — and their doing so is accurate feedback rather than insubordination.
The Mandated Platform Nobody Uses
An organisation invests eighteen months building an internal developer platform. Leadership mandates its use. A year later, half the teams have found exemptions, a third use it minimally while maintaining their own tooling alongside, and the remainder complain continuously.
The usual explanation is that developers resist standardisation. Occasionally true and mostly wrong.
What generally happened is that the platform was designed around the platform team’s model of the problem rather than the actual workflows of the teams using it. It handles the common case adequately and provides no path for the exceptions that constitute a large fraction of real work. Onboarding requires learning concepts specific to the platform. Debugging requires understanding both the abstraction and the thing underneath it. And the documentation describes the intended flow rather than the situations people encounter.
Faced with that, working around the platform is the rational choice for someone with a deadline. The workaround is not a discipline problem — it is a signal that the platform is not the path of least resistance, which is the only property that determines adoption in practice.
Product, Not Project
The single most consequential framing decision is whether the platform is treated as a project with a completion date or a product with users.
Project thinking produces: a requirements document written once, a launch, a mandate, and a maintenance mode. Success is measured by delivery against the original scope.
Product thinking produces: continuous user research, iteration based on observed behaviour, adoption as the success metric, and a roadmap that changes as needs become clearer.
The difference shows up in specific behaviours. A product team talks to users regularly rather than gathering requirements once. It observes what people actually do instead of relying on what they said they wanted. It treats low adoption as a product problem to diagnose rather than a compliance problem to escalate. And it maintains the platform indefinitely rather than declaring it finished.
That last point is where platform initiatives most commonly fail after apparent initial success. A platform launched and then unmaintained decays — dependencies age, the underlying infrastructure changes, and the abstraction drifts from reality. Teams notice the decay before the platform team does, and they start building their own alternatives quietly.
Golden Paths Beat Guardrails
Two philosophies, with substantially different outcomes.
Guardrails prevent teams from doing things. Policy enforcement, restricted permissions, mandatory approval. This is necessary for genuine safety and compliance requirements, and as a general approach it produces adversarial dynamics — teams treat the platform as an obstacle and invest effort in circumventing it.
Golden paths make the correct approach the easiest one. A well-supported, documented, opinionated route that handles the common case well, with the option to step off it when necessary.
The distinguishing property of a golden path is that stepping off it is permitted. A team with genuinely unusual requirements can use the underlying infrastructure directly, accepting that they take on the operational responsibility the platform would have handled.
This sounds like weakening the platform and is what makes it work. Teams that cannot deviate will either subvert the platform or spend enormous effort arguing for exceptions. Teams that can deviate mostly choose not to, because the golden path is genuinely easier — and the small number who do deviate have real reasons that become valuable input for the roadmap.
The practical form: the golden path handles perhaps 80 percent of cases excellently, documents how to handle the rest, and treats each deviation as a research finding rather than a violation.
The Abstraction Leak Problem
Every platform abstracts something. The difficulty is that abstractions leak precisely when they matter most — during incidents.
A developer deploys through a platform interface that hides the orchestrator. The deployment fails with an error originating three layers down. To diagnose it they must understand the platform’s model, the orchestrator’s model, and how the first maps onto the second. They now need more knowledge than if the platform had not existed.
This is the central tension in platform design, and it is not fully resolvable. What reduces the damage:
Surface underlying errors with context rather than replacing them. Show the actual error and add an explanation of what the platform was attempting.
Make the generated configuration inspectable. A developer who can see the manifests the platform produced can reason about them. Hiding the output entirely means every problem requires platform team involvement.
Provide an escape hatch that does not require abandoning the platform. The ability to override one aspect while retaining the rest, rather than an all-or-nothing choice.
Document the mapping between platform concepts and underlying ones. This is the documentation developers need during incidents and the documentation platform teams least want to write, because it exposes the abstraction’s seams.
The general principle is that abstractions should hide complexity without hiding information. A developer who never needs to know what is underneath is well served; a developer debugging at three in the morning needs to be able to find out.
What Developers Actually Want
Platform teams frequently misidentify the priorities. Observed preferences, roughly ordered:
Fast feedback. Time from commit to knowing whether it works. This dominates almost everything else in perceived productivity, and platforms that add pipeline latency are resented regardless of their other merits.
Local development that resembles production. The ability to run and debug locally without deploying. Platforms requiring a full deployment to test anything are a significant regression.
Self-service without waiting. Provisioning a database, a queue, or an environment without filing a ticket and waiting days.
Comprehensible failures. Errors that indicate what went wrong and what to do about it.
Not having to learn infrastructure they do not care about. This is the genuine value proposition, and it is real.
Escape hatches. The knowledge that unusual requirements are handleable.
Notably absent from the top of that list: a unified dashboard, a service catalogue, or a consistent interface across all tooling. These have value and they are platform-team priorities more than developer priorities. Building the portal first, before feedback speed and self-service provisioning work, is a common and expensive misordering.
Measuring a Platform Honestly
Metrics that reflect whether the platform is working:
| Metric | What it reveals |
|---|---|
| Voluntary adoption rate | Whether it is actually the easiest path |
| Time to first deployment for a new service | Onboarding friction |
| Time to first deployment for a new engineer | Learning curve |
| Deployment frequency, platform vs non-platform teams | Whether it accelerates or impedes |
| Support requests per team per month | Whether it is self-service in practice |
| Exception and workaround requests | Where the golden path is too narrow |
| Developer satisfaction, asked specifically | Direct signal, easy to collect |
Voluntary adoption is the metric that matters most and the one mandates destroy. Once adoption is compulsory, you lose the signal that would tell you whether the platform is good. Teams that have to use it will use it and will not tell you it is worse than what they had.
This is a strong argument for delaying mandates. A platform good enough to be adopted voluntarily by most teams needs no mandate for the remainder; a platform requiring a mandate from the start is a platform whose quality you cannot measure.
Support request volume is the second most diagnostic. A self-service platform generating constant support requests is not self-service — it is a ticket queue with a web interface.
Build Order That Works
Ordered so each stage delivers value before the next begins:
Pick one team and solve their actual problem. Not a platform — a solution for one team, built with them. This produces something real and generates the understanding needed for anything general.
Extract what generalises after the second team. Two teams reveal which parts are common and which were specific. One team reveals nothing about generality.
Make provisioning self-service. Databases, queues, environments, without a ticket. This is usually the largest single friction reduction available and it is felt immediately.
Standardise the deployment path. One well-supported route from commit to production, with the underlying configuration inspectable.
Add observability by default. New services arrive with logging, metrics, and tracing configured. This is high value and invisible when done well.
Then build the portal. A catalogue and dashboard is valuable once the underlying capabilities exist. Built first, it is an interface to nothing.
Add policy enforcement last. Guardrails on a platform teams like are accepted. Guardrails on a platform teams resent confirm their view of it.
The recurring mistake is inverting this — starting with the portal and the policy engine, which are the most visible components and deliver the least until the capabilities underneath them work.
When Not to Build a Platform
Platform investment is not always justified, and recognising that saves substantial waste.
Below roughly five to eight engineering teams, the coordination cost a platform reduces may be smaller than the cost of building and maintaining it. Shared templates and documentation frequently deliver most of the benefit.
Where teams have genuinely divergent requirements — different languages, deployment models, and operational needs — a common abstraction may not exist, and forcing one produces something that serves nobody well.
Where the underlying infrastructure is changing rapidly, an abstraction over it will require continuous rework.
And where the platform team would be one person, the result is a single point of failure that becomes a bottleneck and then a liability when that person leaves.
In these situations, the productive alternative is usually improving the shared foundations — better templates, better documentation, better defaults in the CI configuration — without building an abstraction layer requiring dedicated ownership.
Common Pitfalls
Mandating adoption early. Destroys the signal that tells you whether the platform is good.
Building the portal first. An interface to capabilities that do not exist yet.
No escape hatch. Teams with real edge cases will subvert the platform instead.
Hiding underlying errors. Makes debugging require more knowledge, not less.
Generalising from one team. Produces an abstraction fitted to one workflow.
Treating it as a finished project. Platforms decay without continuous maintenance.
Measuring compliance rather than adoption. Compliance is achievable with a mandate and indicates nothing.
Conclusion
Internal platforms fail for product reasons rather than technical ones. They are built around the platform team’s model, mandated before they are good, and abstract in ways that make debugging harder while making the happy path easier.
What works is treating it as a product with users who could leave. Start with one team’s real problem, generalise after the second, and make self-service provisioning work before building anything that looks like a portal. Provide a golden path that handles most cases genuinely well, and permit stepping off it — the teams that deviate have reasons worth knowing.
Measure voluntary adoption, which means resisting the mandate that would make the measurement meaningless. A platform good enough that teams choose it does not need to be compulsory, and a platform that needs to be compulsory is telling you something you should listen to.
Frequently Asked Questions
At what size does a platform team make sense? Typically past five to eight engineering teams, where duplicated infrastructure work exceeds the cost of building and maintaining an abstraction. Below that, shared templates and documentation usually deliver more per unit of effort.
Should platform adoption be mandatory? Not initially. Mandates remove the adoption signal that tells you whether the platform is good. Once most teams have adopted voluntarily, requiring the remainder is defensible.
How large should a platform team be? Large enough that it is not a single point of failure — three engineers is a reasonable floor. One person owning a platform creates a bottleneck and a serious continuity risk.
How much should the platform hide? Enough that routine work requires no infrastructure knowledge, while keeping the generated configuration and underlying errors accessible for debugging. Hide complexity, not information.
What if teams have genuinely different requirements? Support the common case well and document how to handle the rest directly. Forcing a single abstraction across divergent needs produces something that serves nobody well.
Is a service catalogue worth building? Once the underlying capabilities work, yes — it helps with discovery and ownership. Built first, it catalogues services the platform does not yet help with.
How is platform success demonstrated to leadership? Deployment frequency and lead time for teams using the platform versus those not, time to onboard a new service, and reduction in infrastructure support requests. Adoption alone is necessary but insufficient as an outcome measure.
