The two-pizza team needs a wiki

Amazon's two-pizza team model is one of the most influential ideas in modern organisational design. Keep teams small enough that two pizzas can feed them (roughly 5-8 people). Give each team clear ownership of a defined domain. Let them operate autonomously, making decisions without waiting for approval from a central authority.

The model works. Research consistently shows that small, autonomous teams with clear ownership boundaries maintain higher per-person productivity than large teams. They communicate more efficiently, make decisions faster, and ship more frequently. The communication path explosion that slows large teams is contained within each small team's manageable number of paths.

But the model has a dependency that's rarely discussed in the organisational design literature: it only works if the knowledge layer between teams is strong enough to handle the cross-team coordination that the small-team structure creates.

The between-team problem

When you split a 30-person team into five 6-person teams, you reduce the within-team coordination cost dramatically (from 435 paths to five sets of 15 paths). But you create a new coordination surface: the boundaries between teams.

Team A owns the payments service. Team B owns the user service. Team C owns the API gateway. Each team is autonomous within its domain. But the domains interact: the API gateway routes requests to both the user service and the payments service, and the payments service needs user data from the user service. These interactions require cross-team coordination, and the quality of that coordination depends on how well each team's knowledge is accessible to the others.

If Team A's knowledge about the payments service lives in Team A's heads, Team B has to interrupt Team A every time they need to understand how payments work. The coordination cost hasn't been eliminated by the small-team structure. It's been moved from within-team to between-team, and between-team coordination is often more expensive because the people involved don't share daily context.

The documentation dependency

Small teams work when each team's domain knowledge is documented well enough that other teams can access it without requiring a meeting or a Slack thread.

This means each team needs:

System documentation that describes what their service does, how it works, and how to interact with it. Not just API docs, but architectural context: why it's built the way it is, what constraints it operates under, and what will break if you make certain assumptions about its behaviour.

Decision records that explain the reasoning behind major technical choices. When Team B encounters something unexpected in Team A's service, they should be able to understand why it works that way by reading the decision record rather than scheduling a meeting with Team A.

Change documentation that captures what's changed and why. When Team A modifies their service in a way that affects Team B, the change and its implications should be visible in the documentation rather than communicated through a Slack message that Team B might miss.

Searchable knowledge that's accessible across team boundaries. Team B should be able to search Team A's documentation as easily as their own, and the search should work by meaning so they don't need to know Team A's naming conventions to find what they need.

Self-writing as the enabler

The reason most small-team implementations under-invest in cross-team documentation is that the documentation burden falls on the individual teams, who are already busy with their own work. Asking a six-person team to maintain comprehensive documentation for other teams' benefit, on top of shipping their own features, is asking for the documentation to be perpetually deprioritised.

Self-writing documentation changes this equation. Each team's documentation is generated from their existing activity: PRs, Slack conversations, meetings. The documentation stays current because it's derived from the work itself rather than maintained as a separate task. Other teams can search it because it's part of a unified knowledge layer that spans the entire organisation.

The two-pizza team model is an organisational strategy. Self-writing documentation is the knowledge infrastructure that makes it work. Without it, small teams are just smaller silos, and the coordination cost moves rather than shrinks.

Frequently asked questions

What about team APIs and contracts? API documentation and service contracts are essential but insufficient. They describe the interface but not the reasoning. A team that knows what another team's API does but not why it works that way will make integration decisions based on incomplete understanding. Decision records and architectural documentation fill this gap.

How do we handle dependencies between teams? Document the dependencies explicitly in a shared layer. When Team A knows that Team B depends on a specific behaviour of their service, that dependency should be visible in the documentation so changes that affect it are flagged before they're shipped.

Does this apply to non-engineering teams? The same dynamic applies to any organisation that uses small, autonomous teams. Marketing pods, sales teams, product squads: all need a shared knowledge layer to coordinate across team boundaries without constant meetings.

Related reading: The knowledge scaling problem, Brooks' Law is still right, How to scale an engineering team. Related pages: Self-writing docs, One search, For engineering teams.