Developer Portals
Centralized platforms providing developers with documentation, APIs, tools, and service catalogs in one place.
seed#developer-portal#backstage#catalog#documentation#self-service
What it is
A developer portal is a centralized platform where developers find everything they need: service catalog, API documentation, project templates, health dashboards, and self-service tools.
Components
| Component | Function | Example |
|---|---|---|
| Service catalog | Inventory of microservices, owners, dependencies | Backstage Software Catalog |
| Documentation | Centralized, searchable technical docs | TechDocs, Docusaurus |
| Templates | Scaffolding with best practices | Golden paths |
| Plugins | Integrations with CI/CD, cloud, observability | Kubernetes, Grafana, PagerDuty |
| Scorecards | Service maturity evaluation | Cortex, OpsLevel |
Backstage
Backstage (Spotify, CNCF) is the most popular open-source platform for developer portals. Extensible through plugins.
Benefits
- Reduce time searching for information
- Visibility into the service ecosystem
- Self-service for common tasks
- Accelerated onboarding
When not to build one
- Small teams (fewer than 20 developers) — the overhead of maintaining the portal isn't justified
- If there's no dedicated platform team — a portal without maintenance becomes another abandoned system
- When a good README and a wiki solve the problem
Why it matters
A developer portal centralizes access to services, documentation, APIs, and internal tools. Without it, developers waste time searching for information scattered across wikis, Slack, and repositories. It is the discovery layer that makes the internal platform scalable.
References
- Backstage — Spotify's open-source platform for developer portals.
- Port — Commercial alternative focused on self-service.
- Adopting Backstage — Backstage, 2024. Adoption guide for the most popular developer portal.