Module 01 · The product and its people · 25 min · You are: Platform team
What a platform is, and platform as a product
In this module
- You learn: What a platform is and is not (not a portal, not a tool, not a project), why it is run as a product with users, a product owner and a roadmap, and why the smallest platform that solves the problem is the right size.
- You do: Write the platform description for the example company: a mission, two kinds of human user with the problems you found and where you found them, the owning team, the product owner and three things the platform will not do. Then try a mission that leadership might write, and rewrite it.
- You end with:
platform.yamlin your repo passes the check (ok platform.yaml). It names two users of kindhuman, each with problems and evidence, the ownerplatform, a product owner and three non-goals.
A platform built as a project ends when the tools are installed, and then nobody owns whether anyone uses it. A platform built as a product starts from its users and their problems, has someone who decides what it does next, and says no to most requests. Evan Bottcher, 2018 describes a digital platform as "a foundation of self-service APIs, tools, services, knowledge and support which are arranged as a compelling internal product". You write that down first, because every later file refers back to it.
Open this module in the interactive course to track progress.
Concepts
- Platform
- "An integrated collection of capabilities defined and presented according to the needs of the platform's users" (CNCF Platforms White Paper). Defined by its users' needs, not by the tools inside it.
- Platform as a product
- The first of the seven platform attributes in the CNCF Platforms White Paper. Users, problems, a product owner, a roadmap and feedback, like any product. Using it is a choice the users make.
- Thinnest viable platform
- Team Topologies: platforms that "provide just enough capability without unnecessary complexity" (Team Topologies key concepts). Sometimes a page of documentation is the whole platform.
- Problem with evidence
- A problem you heard in an interview or measured in a ticket queue, with where you found it. A guessed problem builds a platform nobody asked for.
- Non-goals
- What the platform will not do, written down. They let a small team say no without arguing each request again.
A platform is not
| Often confused with | What it really is | Why it matters |
|---|---|---|
| A developer portal | One interface to the platform. The white paper lists "web portals" as one capability among thirteen | A portal over ticket queues is still ticket queues |
| A tool (a cluster, a CI system) | Something the platform is built from | Users want an outcome, not a tool |
| A project | A project ends when it is delivered. A product has users for as long as it exists | Someone must own adoption after launch |
| A ticket desk for shared services | The thing self-service replaces | A queue does not scale with the number of teams |
Sources: CNCF Platforms White Paper, Evan Bottcher, 2018.
The seven platform attributes (CNCF Platforms White Paper)
| Attribute | Where you practise it |
|---|---|
| Platform as a product | This module: users, problems, owner, non-goals |
| User experience | Module 04: a golden path |
| Documentation and onboarding | Modules 04 and 05: the path and AGENTS.md |
| Self-service | Module 03: no capability offered only through a ticket |
| Reduced cognitive load for users | Module 02: team interactions |
| Optional and composable | Module 04: the escape hatch |
| Secure by default | Module 05: agent identity and approval |
Files to know
Open them in your editor or on GitHub; the bullets say what to look at.
Steps
1. Write the platform description
The example company: developers in product teams wait weeks for a namespace and a pipeline, and team leads cannot see what they spend. These are the problems the platform team heard in its first week. Create the file in your editor.
cd ~/platformengr/platform-design
Create platform.yaml
# The platform as a product: who it is for, what it solves for them, and what it will not do.
# Owner: the platform team. Read by the design check (rules P1 to P6).
name: Internal developer platform
mission: >-
A product team goes from an idea to a safe change in production in one day,
without waiting for another team, and an agent can do the routine part of that work inside the same limits.
owner: platform
productOwner: Platform product manager (platform team)
users:
- id: product-developer
kind: human
who: Developers in stream-aligned teams such as team-checkout
problems:
- problem: A new service waits about two weeks for a namespace, a pipeline and DNS, through four tickets.
evidence: Ticket history for the last ten new services, read in the first week
- problem: Nobody knows which of three deployment pipelines is the supported one.
evidence: Interviews with five developers in three teams
- id: team-lead
kind: human
who: Leads of product teams who answer for cost and incidents
problems:
- problem: They cannot see what their team spends on cloud and on AI tools.
evidence: Asked in the quarterly planning review; finance sends one total per month
nonGoals:
- Running the product teams' services for them. Teams own and operate what they build.
- A portal before the APIs. The portal shows and approves what the APIs and Git already do.
- Supporting every tool a team has ever used. One supported path per need; others are on their own.
Run the check. Expect ok platform.yaml on the first line, and All checks passed. at the end. The other seven lines still say not written yet.
npm run check
2. Read it as a user would
A description is only useful if a developer in team-checkout recognises their own problem in it. Read the file as them, with three questions: is my problem there, would I know where it came from, and does the mission promise something I care about?
List the problems the platform is meant to solve. Expect three lines, two for product-developer and one for team-lead:
grep -n "problem:" platform.yaml
And the evidence behind each. Expect three lines too. If you cannot fill one in for your own company, that problem needs an interview before it needs a platform.
grep -n "evidence:" platform.yaml
3. Commit
Save it and let the workflow check it too.
git add -A && git commit -qm "Platform description: mission, users, non-goals" && git push -q
Expect success:
gh run list --workflow design-check --limit 1
Simplified for the course
The problems and evidence are examples. In a company they come from interviews with users and from data such as ticket history, before anything is built.
One file holds the whole description. Larger platforms keep a product brief, a roadmap and user research separately, and link them from here.
Agents are not users yet in this file. They are added in module 05, once you know what the platform offers.
Break it on purpose: Leadership's mission
The CTO reads your file and replaces the mission with what was said at the last all-hands, because "that is what we are doing this year".
You practise: telling an outcome from a roll-out, and rewriting a mission so users can recognise their problem in it.
1. Break it
Change in platform.yaml
- mission: >-
- A product team goes from an idea to a safe change in production in one day,
- without waiting for another team, and an agent can do the routine part of that work inside the same limits.
+ mission: Roll out Backstage and Kubernetes to every team by the end of Q2.
npm run check
2. What you see
Expected: ok platform.yaml. You get: FAIL platform.yaml and, under it, a line with [P2]. Read the whole message: which word did the check find?
3. Fix it yourself
Write a mission the CTO would still sign, that names no tool and says what changes for the users in platform.yaml. Done when npm run check prints ok platform.yaml and you can say which user problem the mission answers.
Hint 1
Look at the problems listed under users:. What would be different for a developer if the roll-out worked?
Hint 2
Start with the user: "A product team goes from ... to ... without ...". Keep the tools for the capability map in module 03.
The fix
Any mission that states an outcome for the users passes. The reference mission already mentions agents; you give them a place in the design in module 05.
Change in platform.yaml
- mission: Roll out Backstage and Kubernetes to every team by the end of Q2.
+ mission: >-
+ A product team goes from an idea to a safe change in production in one day,
+ without waiting for another team, and an agent can do the routine part of that work inside the same limits.
npm run check
git add -A && git commit -qm "Mission: an outcome, not a roll-out" && git push -q
After you fixed it: the five questions
- What failed?
- The design. Its mission described a roll-out, so nobody could tell when the platform was succeeding.
- How was it detected?
- By rule
P2of the check, before anyone built anything. - Who responds?
- The platform's product owner, with the CTO.
- How is it corrected?
- Rewrite the mission as an outcome for the users; move the tools to the capability map, where they belong.
- How is it prevented?
- Review the mission with two or three users each quarter: if they cannot find their problem in it, it is the wrong mission.
Quiz
- Which description fits "platform as a product" best?
- The platform team installs a standard tool set and hands it to the operations team to run
- The platform has users with known problems, an owner who decides what comes next, and it is measured by whether teams choose to use it
- Every team must use the platform, and the platform team decides which tools are allowed
- Your platform team is two people. What does "thinnest viable platform" suggest?
- Offer just enough to solve the users' biggest problem, even if that is documentation and a template
- Wait until there is budget for a full platform so it does not look unfinished
- Copy the platform of a large company so nothing is missing later
- Why does every problem in
platform.yamlneed evidence?- The check cannot parse a problem without it
- Leadership will not approve a platform without a reference for every line
- A problem you heard or measured is real; a guessed one builds a platform nobody asked for
Answers
- The platform has users with known problems, an owner who decides what comes next, and it is measured by whether teams choose to use it Users, problems, an owner and adoption by choice are what make it a product.
- Offer just enough to solve the users' biggest problem, even if that is documentation and a template Team Topologies' TVP is just enough capability without unnecessary complexity.
- A problem you heard or measured is real; a guessed one builds a platform nobody asked for Evidence keeps the platform pointed at real problems.
Field note
The best platform mission I have seen fitted on a sticky note: "a team can ship a new service on its first day". Every request after that was answered with one question: does it get us closer to that? Most did not, and saying so got easier each time.