The IDP Adoption Problem
You spent 6 months building an Internal Developer Platform. The launch email went out. And then... nothing. Developers kept using their old workflows, and the portal gathered dust.
We've seen this pattern at a dozen organizations. The problem is almost never the technology — it's building a portal that solves problems developers actually have, in ways that feel natural to their workflows.
Here's the checklist we use at Ailesol to evaluate and build developer portals that achieve 80%+ adoption rates.
Tier 1: Foundation (Must-Have)
These are non-negotiable. Without them, your portal won't get a second look.
1. Service Catalog
A single source of truth for every service, its owner, dependencies, and health status.
# What developers should see for each service
service:
name: payment-service
owner: team-payments
lifecycle: production
tier: critical
tech_stack: [Node.js, PostgreSQL, Redis]
dependencies: [auth-service, notification-service]
links:
repo: github.com/org/payment-service
dashboard: grafana.internal/d/payments
runbook: wiki.internal/payments-runbook
oncall: pagerduty.com/schedules/payments2. Software Templates (Golden Paths)
One-click service creation with best practices baked in. A developer should go from "I need a new service" to "my service is deployed to staging" in under 30 minutes.
3. TechDocs
Documentation that lives next to the code, rendered beautifully in the portal. Markdown in the repo, rendered in Backstage.
4. Search
Fast, full-text search across services, documentation, APIs, and teams. If developers can't find it in 10 seconds, it doesn't exist.
5. Authentication & RBAC
SSO integration (Okta, Azure AD) with role-based access. Teams should only see and manage what they own.
Tier 2: Self-Service (High-Value)
These features are what transform a portal from "nice to have" into "can't live without."
6. Environment Provisioning
Self-service environment creation — dev, staging, preview environments — without filing a ticket.
Developer clicks "Create Preview Environment"
→ Terraform provisions infrastructure
→ ArgoCD deploys the application
→ URL is generated and returned
→ Environment auto-expires in 72 hours
Total time: 3-5 minutes
Old process: 2-3 days via Jira ticket7. CI/CD Pipeline Visibility
See build status, deployment history, and rollback options directly in the portal. No more context-switching to Jenkins or GitHub Actions.
8. API Catalog
Auto-discovered API documentation with OpenAPI specs, usage examples, and dependency graphs.
9. Cloud Resource Management
View and manage cloud resources (databases, queues, storage) owned by your team. Request new resources through self-service workflows.
10. Secrets Management
Self-service secret creation and rotation, integrated with Vault. No more Slack DMs asking for database passwords.
Tier 3: Intelligence (Differentiators)
These features make your portal genuinely loved.
11. Service Scorecards
Automated quality scores for every service across dimensions like documentation, test coverage, security, and operational readiness.
scorecard:
payment-service:
documentation: 85% # Has README, API docs, runbook
test_coverage: 72% # Unit + integration tests
security: 90% # No critical CVEs, secrets scanned
operations: 68% # Has alerts, but missing SLOs
overall: 79% # Grade: B+12. Dependency Graph
Visual map of service dependencies — who calls whom, what breaks if this service goes down.
13. Cost Dashboard
Per-service cloud cost attribution. Every team should know what their services cost to run.
14. Incident Integration
Link incidents to services. Show incident history, MTTR trends, and active incidents on the service page.
15. Onboarding Workflows
Guided checklists for new team members: clone repo, set up local dev, access dashboards, join on-call rotation.
Tier 4: Advanced (Best-in-Class)
These separate the best platforms from the rest.
16. AI-Powered Search & Chat
Natural language queries: "Which services use PostgreSQL 14?" or "Show me all services without SLOs."
17. Custom Plugins
A plugin system that lets teams extend the portal with their own tools and workflows without modifying the core platform.
18. Developer Surveys & Feedback
Built-in feedback mechanisms. Track developer satisfaction (DevEx score) and use it to prioritize platform improvements.
19. Compliance Dashboard
Show compliance status per service: SOC2 controls met, security policies applied, audit evidence collected.
20. Platform Health Metrics
Meta-dashboard showing platform adoption, template usage, self-service request volume, and time-to-first-deploy for new services.
Measuring Success
Track these metrics to know if your IDP is working:
| Metric | Target | Why It Matters |
|---|---|---|
| Portal DAU / total devs | > 60% | Are people actually using it? |
| Template adoption | > 80% of new services | Are golden paths being followed? |
| Time to first deploy | < 1 day | How fast can new devs ship? |
| Self-service vs tickets | > 70% self-service | Are you reducing toil? |
| Developer satisfaction | > 4/5 | Do people like using it? |
Getting Started
Don't try to build all 20 features at once. Our recommended phased approach:
Phase 1 (Weeks 1-4): Features 1-5 (Foundation) Phase 2 (Weeks 5-8): Features 6-10 (Self-Service) Phase 3 (Weeks 9-12): Features 11-15 (Intelligence) Phase 4 (Ongoing): Features 16-20 (Advanced)
The key is shipping something useful quickly and iterating based on developer feedback.
Want help building your IDP? Let's talk about your platform strategy.