Reading Team Topologies with snacks
Team Topologies is a short book that reads best out loud with other people. Notes on what I'd want to argue about over lunch, and where it gets misused.
If I were picking a book for an engineering book club this year, the kind with sandwiches, I’d pick Team Topologies by Matthew Skelton and Manuel Pais. It came out in 2019 and has quietly become the thing everyone cites the moment a company says the words “platform team.” It’s short and dense, and what it really hands you is a vocabulary, which is only useful if the people around you speak it too. Which is the best argument for reading it as a group, since a vocabulary you learn alone is mostly a party trick.
The book starts from an old observation, that a system ends up shaped like the communication paths of the organization that builds it. I’ve always found that idea a little spooky, like noticing that an old house has started to resemble the family living in it. The stairs creak where people argue. If it’s true, then you can’t design the software and the teams separately and hope they meet in the middle. The authors lean on what’s been called the inverse Conway maneuver: decide what architecture you want, then shape the teams so that architecture is the one the organization drifts toward on its own. They also warn against the naive version of this, where someone redraws the org chart on a Friday and expects the codebase to rearrange itself by Monday. Software has inertia. So do people.
I like that the book takes the word “team” seriously before it does anything clever with it. A team, in their usage, is a stable group of roughly five to nine people working toward a shared goal, and it’s the smallest unit the organization hands work to. Not individuals. Teams. They tie the size limit to research on how many people any of us can know and trust well, and then scale it outward in rings, so groups of teams get capped at a few dozen, then around a hundred and fifty, before things start fraying. I’m not sure the anthropology is as precise as the round numbers make it look. I’m also not sure it matters. Anyone who has sat in a standup with fourteen people knows something has broken, even if they can’t cite the paper.
They also want teams to be long-lived. You are moving work to teams rather than people to work. This seems obvious enough, but if you think through how planning typically works, you have some new initiative and then someone grabs two engineers from over here and one from over there and you have a squad...well, in the book they say that it takes a while for a team to learn how to be a team. And every time you reshuffle, you lose all that learning. This makes sense. It’s also a little uncomfortable because it’s so easy to do that reshuffling when you’ve got a deadline breathing down your neck.
The one thing I’d want to spend time thinking about on my second sandwich is cognitive load (a nice way to say “how much can a bunch of people keep in their heads without it leaking out the other end”). They steal a tri-partition from learning research. Problem-related load (“what language do I need to know? How does the framework want me to structure things?”). Environment-related load (“what do I need to know about the environment that has nothing to do with the problem. Like how to remember the four obscure commands you need to invoke to get your test environment running”). And the part that matters most: the load you invest in understanding the business domain well enough to make good decisions in the business domain. Recommendations? They say you want to cut the first two via training and good tool selection. And get the second one down to zero. And keep as much load as possible for the third.
I like this way of thinking about things because that middle bucket is so obvious when somebody points it out. Say you have a team responsible for your checkout flow. Officially their job is payments. But they’re also responsible for the tax calculation service they were left with. And a fraud rules engine that nobody else was interested in. And two mobile release trains. And some deploy script they wrote that has a “don’t run this on Fridays” line in the README. And a nightly reconciliation process that pings someone once a month or so. None of the engineers are dumb. But much of their week is spent with environment trivia bouncing around in their brains. And they get to do work on payments - which would actually improve the checkout experience - when they have time. And you could expand the team with new hires. And they’ll gently recommend that once you get above a certain threshold you’re no longer a team. You’re a bunch of individuals with a shared calendar.
The surprising thing is that it’s pretty unscientific. They don’t want you to count lines of code. Services. Some languages chatter a lot. Some abstractions make the code shorter without simplifying it. Instead, they suggest you ask the team, without judging them, if they feel confident that they can react to the work they’re being asked to do in a reasonable time period. Then how many different domains they’re dealing with, and how complex they are. That’s it. It’s like laughably low tech. I think it’s probably better than most dashboards. The people doing the work usually have an idea of how much work they’re doing.
They suggest that each team should have a team API. I think that’s one of the more subtle best ideas of the book. A team’s API is not just the endpoints and the libraries. It’s also how they communicate when they change things, what kinds of documentation they provide, what’s the best way to reach them, what are they working on right now and next, how do they handle pull requests from outside the team. They propose that the teams should design and test their API the same way you’d design and test any other API. Like, would another team be able to easily use this or would they have a confusing experience. I pictured a team doing a usability test on themselves. It’s funny but also a good idea.
Then there’s four kinds of teams and three kinds of interactions. Most teams should be stream aligned. They should own the flow of work for some piece of product, end-to-end. Enabling teams help people learn a new skill and then they get out of the way. Complicated subsystem teams own the parts of the system that require specialized knowledge. The hard math or media processing. Not something you expect all your product engineers to have in their toolbox. The platform teams offer internal services that let other people just get moving. The whole idea is that you have your stream aligned teams. The other three teams should make that work easier.
You can interact through a period of intense collaboration, through service consumption or through facilitating learning. The interesting and easily missed part is that the authors believe these interactions are going to evolve and spend a late chapter talking about organizational sensing, looking for indicators that a boundary needs to be different. Collaboration is how you define a boundary. Service is where you end up after you find the boundary. Eternal collaboration looks like an undocumented merger.
They have a chapter on software boundary drawing, nice phrase fracture planes, the natural places you can break a system. You can break along business domains, but they give other things like regulatory compliance, dramatically different change rates, risk, isolation of performance, technology, who you are serving. I like this list of things because it’s an implicit “you can break for something other than ‘hey, the domain model says so’”. Sometimes the real reason you’re breaking things up is that one’s deploying twice a day and you need to get through an audit. They also talk about hidden monoliths, where the system diagram looks decoupled but they’re on the same database or they need to be deployed as a set (like a couple houses with different front doors but one bathroom).
The platform chapter. That’s what I would want us to be doing mostly with our lunch.
The book describes a platform as an internal product. It’s something other teams opt-in to use because it makes their life better. Something that should be minimized as much as possible while still being useful. They refer to this as the thinnest viable platform. Sometimes this might just be a page of documented conventions. Some templates. No team. Like, the doctor telling you you might not need surgery, you just need to drink more water.
The usual failure (and I suspect most of the audience has experienced it) is that the platform folks eventually become a helpdesk. You can’t just do the usual thing. That’s in somebody else’s backlog. That’s ‘service-dressed collaboration’ per the book. You can easily mention this and it’s non-controversial because it has a name. Say you’re a product team that wants a new queue. In the helpdesk situation they’ll ask for it. Wait until the platform folks do their planning thing. Then answer three clarifying questions over a week. Eventually they’ll get a new queue that’s a bit different from what they wanted. With self-service they’d just clone a template, change two things, and the platform team will only know about it if the template was hard to understand. And that means the platform team appears less busy, which is part of why it’s difficult to sell it internally. Busy is a great photo.
Questions I’d scribble on the whiteboard then pretty much ignore when a more interesting conversation develops:
- Which of our teams owns the most unrelated things, and what would it hand off first?
- What type is each team, going by how it actually spends its week?
- Which pair of teams has been “collaborating” for a year without ever drawing a line?
- If the platform team vanished for a month and left only docs and templates, what would break?
I do have some beef. First of all, too well-behaved a vocab. You’ll just want to relabel everything. “Infrastructure” team in your company is renamed “platform” team - you just slap it on a slide. But nothing else changes. The way people behave has nothing to do with your slide.
Second, it implies that your org is big enough that you really need the model. If you have a few teams or so, probably you want stream-aligned teams plus one person managing paved road. But at that scale it’s more of overhead with fancy name to have an enabling team. And as authors mention that topologies are fractal and can be adapted. But I want to see even stronger statement when not to use their ideas. If you have a smaller company, you may come out from the book with a proposed org structure suitable for your org four times bigger. Like buying dining table for your future family.
Third, yes platform as product is true. And costly. It requires actual product skills for internal audience. Few companies allow budget for that. Otherwise platform team will just focus on stuff they find interesting. It’s very human, but not very helpful.
But I will choose. Partly because ideas, but partly I like to imagine how bunch of engineers with sandwiches make their own org chart on whiteboard. Trying to count how many stuff are responsible in each box. And debate if that one box is actually ticket window in disguise.