Overview

This chapter covers the core features and capabilities of Platform Team Playbook.

Overview

The Platform Team Playbook is a comprehensive operational guide for building, scaling, and running an internal platform engineering team. It covers organizational structures, day-to-day operations, metrics, developer experience measurement, and long-term scaling strategies.

This playbook distills proven patterns from mature platform organizations into actionable templates, scripts, and frameworks that you can adopt immediately.

What's Included

Team Structures (structures/)

Tools (tools/)

Operations (operations/)

Metrics (metrics/)

Surveys (surveys/)

Reviews (reviews/)

Scaling (scaling/)

Knowledge Management (knowledge/)

How to Use This Playbook

Treat the playbook as an operating system for a platform team, not a document to read once. Begin with evidence, select a small number of practices, assign owners, and review outcomes on a fixed cadence.

Assess Current Maturity

Run surveys/developer_experience.md before changing the roadmap. Distribute the 30-question survey to all platform consumers, keep responses anonymous, and report team-level results only when at least five people respond. Calculate the composite DevEx score and retain dimension scores for CI/CD, infrastructure, observability, documentation, support, and security.

Combine survey results with operational evidence: lead time to first production deployment, self-service completion rate, SLO attainment, incident volume, support-request age, and platform adoption by team. Rate each capability from 1 to 4:

1. Reactive: work arrives through individuals; ownership and service levels are unclear.

2. Repeatable: common requests have documented processes, but delivery remains manual.

3. Self-service: golden paths, catalog entries, automation, and measurable SLOs exist.

4. Optimized: usage data and feedback continuously shape priorities and cost.

For example, a CI/CD survey score of 2.6, frequent infrastructure-caused failures, and no published owner indicate a Reactive or early Repeatable capability. Record the score, evidence, desired level, owner, and review date in an adoption roadmap.

Use the Templates in Sequence

Create a 90-day adoption roadmap with no more than three outcomes. A practical first quarter might be: publish the ten highest-volume services, launch one self-service golden path, and establish incident ownership. For each outcome, specify baseline, target, accountable owner, milestone, dependency, and success metric.

Use operations/service_catalog.md to document each service’s ID, owner, lifecycle status, access method, support tier, SLOs, documentation, dashboard, and on-call route. Example: publish “Namespace Provisioning” as GA, Tier 2, self-service through the portal, with a target of completion within five minutes.

Your developer portal is the presentation layer for those entries. Start with catalog discovery and links; then add templates and automated actions. A portal card for Namespace Provisioning should show ownership and SLO data from the catalog, link to the runbook, and launch the approved request workflow. Do not let the portal become a second, contradictory catalog.

Run Focused Workshops

Schedule a 90-minute working session with platform engineers and representative consumers:

• 0–15 minutes: state the user problem and review baseline evidence.
• 15–35 minutes: map the current journey and mark delays, handoffs, and failure points.
• 35–60 minutes: complete the relevant template together.
• 60–75 minutes: prioritize changes by user impact and effort.
• 75–90 minutes: assign owners, dates, and measurable acceptance criteria.

Use tools/raci_generator.py after the session to formalize accountability. Send the completed catalog entry or roadmap—not meeting notes—for asynchronous review within two business days.

Customize by Organization Size

At 10 engineers, favor a lightweight centralized model: one platform owner, two or three catalog entries, business-hours support, and Markdown documentation. Avoid building a portal before recurring demand is proven.

At 50 engineers, establish a dedicated team, adopt the hybrid model, publish standard golden paths, define Tier 1 and Tier 2 services, and run a regular on-call rotation. A portal becomes valuable for discovery and common provisioning.

At 200+ engineers, use a federated or hybrid structure with domain liaisons, explicit service ownership, paved-road standards, 24/7 coverage for critical services, and portal plugins backed by APIs. Apply governance through reusable templates and policy automation, not central ticket approval for every change.

Measure and Adjust

Build the dashboard described in metrics/platform_dashboard.md. Track adoption, reliability, satisfaction, and cost efficiency monthly; rerun the DevEx survey quarterly. Compare against the recorded baseline: service adoption, self-service completion, onboarding time, SLO attainment, MTTR, NPS, and cost per engineer. Use reviews/quarterly_review_template.md to explain movement, missed targets, and the next three roadmap outcomes. Progress means consumer behavior and outcomes improved—not simply that more platform features shipped.