PlatformEngr® Platform fundamentals course

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.yaml in your repo passes the check (ok platform.yaml). It names two users of kind human, each with problems and evidence, the owner platform, 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 withWhat it really isWhy it matters
A developer portalOne interface to the platform. The white paper lists "web portals" as one capability among thirteenA portal over ticket queues is still ticket queues
A tool (a cluster, a CI system)Something the platform is built fromUsers want an outcome, not a tool
A projectA project ends when it is delivered. A product has users for as long as it existsSomeone must own adoption after launch
A ticket desk for shared servicesThe thing self-service replacesA 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)

AttributeWhere you practise it
Platform as a productThis module: users, problems, owner, non-goals
User experienceModule 04: a golden path
Documentation and onboardingModules 04 and 05: the path and AGENTS.md
Self-serviceModule 03: no capability offered only through a ticket
Reduced cognitive load for usersModule 02: team interactions
Optional and composableModule 04: the escape hatch
Secure by defaultModule 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 P2 of 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

  1. 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
  2. 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
  3. Why does every problem in platform.yaml need 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
  1. 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.
  2. 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.
  3. 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.

Report a problem with this module