Developer Portals for Platform Adoption: CNPA practice questions

A developer portal is the web interface where developers discover what the platform offers, start new projects, find documentation and see the state of the software they own. The CNCF Platforms White Paper lists web portals for observing and provisioning products and capabilities as the first of its capability domains and names Backstage as an example project. Portals matter for adoption because a capability nobody can find is a capability nobody uses.

Backstage, a CNCF incubation project, is the reference implementation. Out of the box it combines three features. The Software Catalog keeps track of all software and its owners. Software Templates, found under /create, let a developer choose a template, fill in its inputs, review them and run a set of steps that load a code skeleton, fill in variables and publish the result to a location such as GitHub or GitLab, with the organization's practices already built in. TechDocs gives each component documentation written in Markdown next to its code, a docs-like-code approach, and shows it on the component's page in the catalog. A growing ecosystem of open source plugins brings other tools into the same view. Backstage's documentation frames the benefits per audience: engineering managers can maintain standards, developers get one place to build software and find documentation, and platform engineers get an extensible way to integrate new tools.

Adoption is where portals are most often misunderstood. The Platform Engineering Maturity Model describes adoption levels from Erratic, where teams discover tools through rumors and chance conversations, through Extrinsic push, where incentives or mandates drive use, to Intrinsic pull, where users choose platform capabilities for the value they bring, and finally Participatory, where users contribute fixes and new capabilities back. Self-serve portals, golden-path templates and good documentation are listed among the things that enable rapid use at the pull stage. A portal does not create pull by itself, though. If the processes behind its buttons are still manual tickets, it is just a nicer-looking queue.

Measuring adoption is part of the job. The white paper suggests tracking active users and retention, the number of capabilities provisioned and satisfaction surveys such as Net Promoter Score, and DORA's platform guidance recommends measuring how quickly new teams onboard and whether they keep using the platform. Platform teams can also drive adoption deliberately with announcements, engaging demos and regular feedback sessions, and by starting with a few engaged partner teams who later champion the platform to others.

Misconceptions to avoid: the portal is not the platform, only one of its interfaces; installing Backstage starts a product effort rather than finishing one, because the catalog and templates need ongoing curation; and pushing everyone onto the portal by decree tends to produce resistance rather than adoption.

Expect associate-level questions on what a portal provides, which Backstage feature fits a need such as scaffolding a service or publishing docs, and which signals show that adoption is healthy.