I’d market an internal developer platform by helping engineers ship - not by promoting its features. Start with 2–3 common tasks, such as creating a service or deploying a scheduled job. Give each task a documented path, a named owner, and clear support limits.
Here’s the approach I’d use:
- Find the friction: Ask teams where setup, deployment, and reviews get stuck.
- Test before rollout: Have a small pilot group use templates and task-based docs. Include a skeptical team.
- Teach through use: Let champions demo complete workflows, then offer help with live repositories.
- Measure results: Compare self-service completion, repeat use, delivery results, and engineer feedback over a 30- or 90-day window.
- Close the feedback loop: Fix repeated blockers, explain changes, and provide migration steps before retiring a path.
My test for adoption is simple: Can engineers finish the task without extra help - and use the platform again? That matters more than demo attendance.
2. Build golden paths around common tasks
Once ownership is clear, turn the platform into a few repeatable workflows engineers can use.
A golden path is a supported workflow, not a tool catalog. It brings together the minimum needed to finish a common task. Making first use repeatable helps drive adoption. Start with two or three common tasks, and name each path after the task engineers want to complete.
Examples include creating a web service or deploying a scheduled job.
Guide engineers to their first deployment
Pair each repository template with a task page that explains its purpose, intended users, prerequisites, expected time, outputs, owner, and support channel.
Group requirements into access, build and test, security, and runtime visibility. Cover runtime constraints, permissions, secrets, and readiness checks. Where relevant, include template defaults for CI/CD, tests, security checks, secrets, health checks, logs, metrics, alerts, and rollback steps.
Walk engineers from template selection through nonproduction deployment to production release. Provide copyable commands, expected outputs, and fixes for common problems. Make deployment something engineers can verify, not just a set of steps to follow.
Use Backstage only if it fits your stack and maintenance budget. Its Software Templates can load code skeletons, substitute variables, and publish the resulting component to a repository or another destination. A documentation site with linked templates is a simpler starting point if a portal would add work without improving the deployment journey.
Then make clear which path is standard and which departures need review.
Explain supported paths and exceptions
Publish the recommended route before teams start. For each exception, record the reason, risk, owner, review date, allowed changes, and effect on support.
| Decision state | Recommended route | Support boundary |
|---|---|---|
| Fits the standard path | Use the production-service template | Platform team supports the template, CI/CD, default security controls, and observability integration |
| Needs a supported variation | Start with the closest path; request consultation before changing defaults | Platform team advises; application team owns application-specific behavior |
| Needs feasibility review | Consult before implementing unusual networking, regulated-data controls, or a nonstandard runtime | Confirm feasibility, ownership, and additional engineering work |
| Falls outside the deployment model | Use a separate support model with its own deployment process, runbooks, and operations contacts | No end-to-end platform support unless brought into scope |
3. Help teams adopt the platform
Treat the pilot as research, not a launch event. Recruit a small group that reflects different app types, risk levels, and familiarity with tools. Include one skeptical team. Record how each team deploys today and where they get stuck. Then match onboarding to their experience: guided practice for newcomers, a migration checklist for experienced teams, and a step-by-step path for teams maintaining monoliths. Use the pilot to check that teams can follow the documented golden path without extra help.
Test task-based docs with engineers
Ask pilot engineers to use the docs to complete a golden path task, connect an approved dependency, find the service owner, and troubleshoot a failed deployment. Watch first. Coach only when needed. If you embed a platform engineer, log every intervention so their help doesn't hide gaps in onboarding.
Separate missing instructions from broken workflows. A missing prerequisite may call for a documentation fix. A task that fails despite correct instructions needs a platform fix. Clear common blockers, then have a different engineer repeat the task before opening access to more teams. This checks whether the platform reduces cognitive load.
Use champions and demos to teach workflows
Recruit champions from different pilot teams and keep their role focused: test golden paths, demo tasks, and report recurring blockers. Give them early access and a clear escalation channel. Run short demos that show repository creation, deployment, ownership discovery, and one recovery step - not a feature tour. Use these sessions to find the remaining blockers before rolling out to more teams.
Follow each demo with task-focused office hours where engineers bring live repositories. Check whether they can complete the workflow on their own and return for their next change. Publish feedback responses that explain what changed, what's deferred, and what remains unsupported. Attendance shows interest; repeat use shows adoption. The platform engineering community’s CNCF maturity model considers adoption alongside the value teams receive. Use the pilot results to define the adoption and delivery metrics you'll track next.
4. Measure adoption and delivery outcomes
Once teams have used the golden path in the pilot, check whether they can use the platform without extra help. Set the baseline before rollout. Define eligible teams, services, and tasks. Record the platform and runtime versions, approval rules, and known exceptions. Over a consistent period, such as 30 or 90 days, measure completion rates, median time to first production deployment, support requests, deployment frequency, failed deployments, and recovery time.
Track completion, self-service, and repeat use
Keep documentation visits and demo attendance separate from successful use. Completion means reaching production with all required checks passed. Self-service completion means getting there through documented paths, without manual help from the platform team.
Report completions against both eligible services and workflow starts, showing counts alongside percentages. Track where users abandon the process: permissions, configuration, testing, approval, or deployment. Group the results by workflow, stack, and team type.
Measure the self-service completion rate for eligible tasks, median time from request to completion, and how often intervention was needed - and why. Track repeat use within a defined 30- or 90-day window.
Also report the percentage of eligible services on the recommended version, how many use deprecated versions, and the reasons for exceptions. Treat version exceptions as product or migration issues, not failed adoption or user noncompliance.
Compare delivery metrics and engineer feedback
Start with adoption metrics, then compare delivery outcomes against the same baseline.
Follow DORA guidance for change lead time, deployment frequency, change failure rate, and recovery time. Faster releases aren't automatically better if failures or recovery times also increase.
Compare the same services before and after adoption, or match similar teams over the same period. Record changes in staffing, migration, and release policies so you don't credit the platform for every improvement.
Pair the metrics with short questions about effort, confidence, where engineers needed help, and which workarounds they used. Use the findings to find friction, not rank engineers. Review friction weekly or biweekly, and track adoption and delivery trends monthly.
5. Use feedback to plan the next release
Use adoption data to see where engineers still get stuck, then use their feedback to shape the next release.
Fix repeated blockers and explain changes
Keep champion feedback, support requests, and delivery trends in one feedback register. Record the workflow, affected team, source, frequency, impact, proposed action, owner, and status. Prioritize repeated blockers in high-value golden paths. Before adding a fix to the release, check it with the teams that reported the problem.
Before retiring a path, identify active users, provide a migration route, and set a deadline. Explain which support will end, document the supported alternative, and name the owner of migration help. Ship updated docs with the change - not afterward.
Publish a changelog that covers the problem, affected teams, migration steps, deadline, limits, and help contact. Link directly to the updated workflow so engineers can act.
Review platform goals with application teams
Once you’ve scoped the next release, review it with the teams that use it. Bring application teams, platform engineering, security, and operations together each quarter to confirm that the golden path still matters. Use adoption results and developer-experience feedback to decide which templates, docs, or ownership boundaries need work. End the review with a few commitments, each with an accountable owner, success measure, target date, and feedback checkpoint.
Expand only after engineers can reliably complete the first golden path without unnecessary help. Following Team Topologies, the next release should remove friction and give engineers more autonomy.
FAQs
How do we prioritize our first golden path?
Prioritize the golden path that clears the highest-risk bottleneck - whether that’s reaching a first success after onboarding or deploying fast and reliably. Tie that choice to DORA outcomes.
Define the target platform user role, then draft a workflow developers can clone and build in stages. Publish the setup steps, tradeoffs, and exit criteria so developers know how to start, what to weigh, and when they’re done.
Measure adoption through engaged visits, qualified actions, and pipeline influence - not views. Track usage as a leading indicator of ramp-up, self-service, and DORA impact.
How can we win over skeptical engineers?
Lead with proof, not promises, and let engineers try the tool themselves. Swap jargon for documentation, runnable code samples, tutorials grounded in actual use cases, and candid post-mortems. Keep time to first value under 15 minutes so engineers can get a working result without sales pressure.
Build lasting trust by being open with your community. Answer technical objections publicly and share measured results that engineers can use to make the case for your tool internally.
How do we measure adoption when platform use is mandatory?
Even when developers must use a platform, usage alone doesn’t tell you whether it’s working. Measure adoption by how much the platform reduces cognitive load and improves developer productivity.
Track golden path adoption, the time it takes new hires to make their first production deployment, self-service ratios, and time saved on repetitive infrastructure tasks.
Use DORA metrics - deployment frequency, lead time for changes, mean time to recovery, and change failure rate - to assess gains in delivery performance and operational health.