30 May 2024 / Technical leadership / 8 chapters

Review whether the team can still make one product

From How technical decisions break down as a team grows

When you review this periodically, look for incompatible behaviour that's already forming. Counting decision documents won't show you that. I'd sample recent changes that crossed team boundaries and trace the product concepts they touched.

Things I'd check:

  • Shared contracts and product terms have owners you can identify.
  • People can find the current decision without asking in a private channel.
  • Records make it clear what's proposed, accepted or replaced.
  • Local teams know which changes need wider review.
  • Review happens before the implementation gets expensive to change.
  • Affected consumers are involved when a contract changes.
  • Migration and mixed-version behaviour get considered.
  • Tests cover the behaviour the decision promised.
  • Exceptions have a reason, a scope and an owner.
  • Old records and docs point to the current guidance.

Then pick one shared concept and follow it through storage, APIs, events, interface copy and operating procedures. If the definitions don't match, treat the repair as product work with a compatibility plan. A documentation tidy-up won't fix it.

Ask a few newer team members where they'd look before changing that concept. If the answer is "ask so-and-so", fix the source and links before adding another onboarding session.

Look at what the review process costs, too. Teams should be able to point to local decisions they made without central approval, shared changes reviewed quickly, and higher-stakes proposals that got a deeper look. If everything goes down the same path, the boundaries are probably too vague.

Back to where this started: as a team grows, technical decisions mostly break down by getting made twice, in different places, by people who each had a sensible reason and couldn't see the other call. What I'd want is for the shared decisions to be written down with an owner and reviewed before incompatible code exists, while everything else stays with the team doing the work. If you want somewhere to start, pick one decision that's currently being made in several places. Write its current meanings side by side, name the people who'd be affected by picking one version, and put that proposal through the same review route you expect everyone else to use.

All articles