Platform Engineering & Developer Experience

Manual chapter on crafting internal platforms and measuring developer experience.

Source: content/manual/04-platform-engineering/index.md

Platforms exist to remove friction for product teams. This chapter explains how to treat the platform as a product, map capabilities to DORA outcomes, and keep developer experience (DevEx) measurable so investment decisions stay grounded.

Platform as a product

Establish a roadmap with quarterly themes (onboarding, observability, release safety).
Define service-level objectives for platform capabilities (scaffolding time, pipeline success rate, mean time to repair incidents caused by platform).
Create feedback loops: DevEx surveys, office hours, support ticket analytics, and feature request backlogs.
Publish a platform charter that explains scope, decision rights, and funding model.

Core capabilities

Golden paths: Templates and tooling for the most common workloads.
Self-service provisioning: Infrastructure APIs guarded by policies.
Observability defaults: Log/metric/tracing integrations included by default.
Governance: Guardrails for compliance, secrets rotation, and dependency hygiene.
Progressive delivery: GitOps, rollout controllers, and feature flag integrations baked into pipelines.

Build or extend these capabilities using:

playbooks/golden-paths-for-devs/index.md for templates and paved roads.
playbooks/internal-platform-architecture/index.md for architecture layers and governance.
playbooks/from-ci-cd-to-gitops/index.md for deployment orchestration.
playbooks/developer-onboarding-as-a-service/index.md for packaged onboarding experiences.

Measuring DevEx

Pair quarterly surveys with objective metrics (lead time, review time, build duration, support ticket volume). See playbooks/measuring-devex/index.md and checklist for cadence.
Track adoption of platform features—CLI usage, template scaffolds, GitOps repos—and sunset unused capabilities.
Expose a public scorecard so product teams understand where the platform invests and how it impacts outcomes.

Operating model

Support tiers: Stream-aligned teams raise requests through portal/Slack; platform triages and pulls enabling teams when coaching is needed.
On-call: Platform owns incidents tied to paved roads and internal tooling with published SLAs. Integrate incident reviews with playbooks/accelerating-mttr/index.md.
Funding & prioritization: Use DORA + DevEx metrics to justify investments. Include product leadership in roadmap reviews to keep effort aligned to business outcomes.
Documentation: Every capability ships with quickstarts, FAQs, and reference architectures stored in the developer portal and playbooks/.

Escalation map

Stream-aligned teams own product domains; platform provides paved roads.
Enabling teams bridge adoption gaps and surface recurring pain to platform roadmaps.
Leadership (see manual/05-team-topologies/index.md) clears funding and staffing hurdles when systemic issues appear.

Common pitfalls

Building capabilities no team requested—validate demand with pilots and adoption metrics.
Ignoring compliance requirements until late in delivery; integrate governance early.
Under-investing in documentation and training, forcing shadow tooling to emerge.
Treating DevEx solely as survey scores; combine quantitative and qualitative insight.

References & further learning

Platform Engineering community patterns (Backstage, Kratix, Humanitec).
CNCF Platform Working Group whitepapers on platform operating models.
“Team Topologies” by Skelton & Pais for organizational interfaces—paired with manual/05-team-topologies/index.md.
Reference your persona research or stakeholder briefs to tailor messaging for CTO, platform leads, and developer audiences.