Platform Engineering and Internal Developer Portals for Mid-Size Teams
The Cultural Shift Nobody Talks About
Here’s the part that doesn’t fit neatly into a diagram: platform engineering changes how teams relate to each other. Developers stop hoarding knowledge. Infrastructure folks stop being ticket-takers. Everyone starts thinking in terms of shared ownership.
That shift takes time. It takes trust. And it takes a platform team humble enough to admit when their first attempt misses the mark.
For mid-size teams, this is the sweet spot. You’re big enough to benefit from structure, small enough to stay nimble. Get it right, and you’ll ship faster, onboard quicker, and sleep better. Get it wrong, and you’ll have built a beautiful portal that nobody visits — a digital ghost town with excellent documentation.
The choice, as always, comes down to listening first and building second.
Picture this: your engineering team has grown from five people to thirty-five. What used to be a quick Slack message — “Hey, can you spin up a staging environment?” — now disappears into a backlog. Nobody knows who owns the deployment pipeline. And honestly, your onboarding docs? They were last updated when Kubernetes was still exciting.
That’s the moment platform engineering starts knocking on your door. Not because it’s trendy (though, sure, it is), but because the chaos has a cost. And for mid-size teams — say, 20 to 200 engineers — that cost hits differently than it does at a giant enterprise or a scrappy startup.
Let’s dive into what platform engineering actually means for teams your size, why internal developer portals matter, and how to avoid the trap of building a platform nobody uses.
What Platform Engineering Really Means (Minus the Buzzwords)
At its core, platform engineering is about treating your internal infrastructure like a product. Instead of every developer cobbling together their own CI/CD setup, you build a shared foundation — golden paths, if you will — that makes the right way the easy way.
Think of it like a well-organized kitchen. In a small team, everyone grabs what they need from the fridge. In a mid-size team, that fridge becomes a disaster zone. Platform engineering is the person who labels the shelves, stocks the essentials, and puts the knives where you can actually find them.
The goal isn’t to restrict developers. It’s to remove the friction that quietly eats hours every week — the “where’s the config file?” and “why did the build fail again?” moments.
Why Mid-Size Teams Feel the Pain Most Acutely
Startups under 20 engineers can survive on tribal knowledge. Enterprises have dedicated platform teams with real budgets. Mid-size teams? They’re stuck in the middle — too big for hallway answers, too small for a 15-person platform org.
Here’s what tends to happen:
- Tool sprawl: One team uses Terraform, another uses Pulumi, and a third… well, they just SSH into servers. Yikes.
- Onboarding drag: New hires take weeks to ship their first change because nobody documented the deploy process.
- Cognitive overload: Developers spend more time wrestling with infrastructure than writing product code.
- Shadow ops: Someone quietly becomes the “person who knows how the cluster works” — and then they go on vacation.
Sound familiar? You’re not alone. In fact, industry surveys keep showing that developer experience ranks among the top concerns for engineering leaders in 2024 and 2025 — right up there with AI tooling and security.
Internal Developer Portals: The Front Door to Your Platform
If platform engineering is the kitchen, the internal developer portal (IDP) is the menu. It’s the single place where developers go to discover services, spin up environments, check ownership, and read docs that are actually current.
Tools like Backstage (originally from Spotify), Port, and Cortex have made IDPs more accessible than ever. But here’s the deal — the tool matters less than the philosophy. A portal is only useful if it solves real problems your developers have today.
What a Good Portal Actually Does
A well-designed IDP typically offers:
- Software catalog: Every service, library, and API — with an owner listed. No more guessing.
- Self-service actions: “Create a new microservice” or “provision a database” without filing a ticket.
- Documentation hub: Tech docs that live next to the code, not in a forgotten wiki.
- Scorecards and standards: Gentle nudges toward best practices — like having tests or a README.
- Environment visibility: See what’s deployed where, and who deployed it.
Notice what’s missing? Anything that feels like a gatekeeper. The best portals feel like a concierge, not a bouncer.
Build vs. Buy: The Honest Trade-Off
This is where mid-size teams often stall. Do you build your own portal on Backstage, or buy a managed solution?
| Factor | Build (e.g., Backstage) | Buy (e.g., Port, Cortex) |
|---|---|---|
| Upfront cost | Lower in dollars, higher in time | Higher in dollars, lower in time |
| Customization | Unlimited — it’s yours | Constrained by vendor roadmap |
| Maintenance | You own it. Forever. | Vendor handles upgrades |
| Time to value | Months | Weeks |
| Best for | Teams with a dedicated platform squad | Teams without spare headcount |
Honestly? Most mid-size teams underestimate the maintenance burden of a self-built portal. Backstage is powerful, sure — but it’s a framework, not a finished product. You’ll need someone tending it regularly.
If you don’t have at least one or two engineers who can own the portal long-term, buying is often the smarter move. And there’s no shame in that.
Starting Small: A Realistic Roadmap
You don’t need to boil the ocean. In fact, trying to launch a full-blown platform on day one is a classic recipe for abandonment. Here’s a more grounded approach:
- Talk to developers first. Ask what slows them down. You’ll hear the same three complaints, guaranteed.
- Pick one golden path. Maybe it’s “deploy a service to staging.” Nail that before expanding.
- Start with a catalog. Even a simple spreadsheet-to-portal migration creates immediate value.
- Measure adoption. If nobody uses it after a month, something’s wrong — and it’s probably not the developers.
- Iterate publicly. Share a changelog. Celebrate wins. Make the platform feel alive.
The teams that succeed treat their platform like a product with real users — because that’s exactly what it is.
Common Pitfalls (Learn From Others’ Bruises)
Sure, platform engineering sounds great on paper. But plenty of teams stumble. Watch out for these:
- Building in isolation: A platform team that never talks to product engineers is basically writing fiction.
- Over-abstracting: If your portal needs its own onboarding doc, you’ve gone too far.
- Mandating adoption: Forced usage breeds resentment. Make it genuinely better, and people will come.
- Ignoring the long tail: That one team with a weird legacy stack? They matter too.
And here’s a subtle one: don’t confuse a portal with a platform. The portal is the interface. The platform is the underlying capability. You need both, but they’re not the same thing.
The Cultural Shift Nobody Talks About
Here’s the part that doesn’t fit neatly into a diagram: platform engineering changes how teams relate to each other. Developers stop hoarding knowledge. Infrastructure folks stop being ticket-takers. Everyone starts thinking in terms of shared ownership.
That shift takes time. It takes trust. And it takes a platform team humble enough to admit when their first attempt misses the mark.
For mid-size teams, this is the sweet spot. You’re big enough to benefit from structure, small enough to stay nimble. Get it right, and you’ll ship faster, onboard quicker, and sleep better. Get it wrong, and you’ll have built a beautiful portal that nobody visits — a digital ghost town with excellent documentation.
The choice, as always, comes down to listening first and building second.