Secrets behind good Team Topology diagrams
This post assumes that you already understand the absolute basics of Team Topologies, but if not, you can quickly get the gist of it here (Infographics — Team Topologies).
One problem new practitioners quickly run into when trying to create a Team Topology diagram is they can’t fit all the nuances and complexities of real life into the picture. It feels like the reality is just infinitely more complex than the examples provided, and this becomes a real blocker for many people who are trying to improve their organization.
Simon Brown (who created The C4 model for visualising software architecture) has spent a fair bit of time working on a very similar challenge with architecture diagrams. While his work does chiefly focus on software architecture, he has also provided a lot of ideas about models and diagrams that can shape your thinking around our Team Topology diagram challenges. Even if you are not a software developer, it is easy to imagine how a software architecture diagram can become overloaded with complexity and quickly become complicated. Simon solves this in lots of ways, but most relevant to us is that his framework enables people to have “one level of detail at a time” by zooming in-and-out to various levels of abstraction, but possibly more importantly he identifies there is a distinction between a “model” and a “diagram”.
A model is a very accurate mapping of the boxes and interactions. It may be a highly complex, multi-dimensional thing that takes months to load up into someone’s mind and hard to explain again, or take a long time and a lot of care to accurately document all the details. Once we craft these understandings, we often need to have a meaningful conversation about them. The trouble is, the model is so detailed and full of nuance that it is often hard to focus a conversation on what matters, or even spend a lot of time trying to sync every individual’s slightly different mental model into one.
This is why we often discuss things with diagrams instead of pure models. A diagram is a way to short-cut all of that and have a meaningful conversation around some focused extraction of the complexity inside that model. The raw form is often too complicated, leads to misunderstandings, information-overload, endless hours correcting or exploring unimportant aspects, or down-right bikeshedding. At the same time, you collectively need to hone and refine your models (often simply mental-models) of how things work. A good diagram can often drive enough alignment across many people so that you don’t need to explicitly indicate every detail either.
So what does it mean for your work with a Team Topology diagram? It might be that you are trying to model all team interactions in detail (which is largely beneficial for you to build a mature mental-model), but the struggle is that the diagrams themselves are not meant to contain endless complexity. Your diagrams are complex because you aren’t trying to tell one good story about org design challenges, you’re trying to tell every story, and all at the same time. Of course it’s too complex!
How might we simplify down our diagrams so they help us have focused discussions?
Diagrams are a visual language. Just like writing a text document, your diagram can also contain a lot of detail that could be removed and still be valuable. Use some of these questions to challenge what you put into your diagrams:
Does this diagram let us focus on one conversation at a time, or is it discussing too much?
Could this be better described with two different diagrams, one that shows discussion topic A and another that shows discussion topic B?
Is there a subset of teams and interactions that I can discuss without invoking the entirety of the company?
Does the diagram focus on one level of abstraction at a time?
Are the interaction arrows breaking down every single type of XaaS provided by a platform (imagine an Auth service and listing all the sub-capabilities that fit inside that) or do we just simplify the message with “Auth”? Do we simplify further to “these two teams interact through a service”? Are we discussing things at the appropriate level of granularity? Too granular? Not enough to surface the problems?
Is the diagram trying to highlight something that isn’t suited to a Team Topology diagram such as component architecture or data mapping? It might help to highlight the problem through interactions, but if you want to get deeper and break apart fine-grained details you’ll need to adapt your tools to zoom in and discuss the nitty-gritty details of a specific software system.
Is the diagram generally confusing despite solving those first two questions?
If I add together all the teams plus interactions in this diagram, is the total sum of visual elements greater than 20?
Do you name things in unexpected ways? For example, mixing up team names, invoking terminology that nobody but you is familiar with, inventing new types of symbols and visual elements that feel intuitive to you but nobody else has seen before? The usefulness of a visual language only goes as far as how many people can read it.
How good is your (mental) model, really?
How big is the drift between reality and your working model? (What I call “model-reality drift”).
How many dimensions are you packing into the diagram at once?
Are you trying to capture all types of states at every nanosecond in time (ephemeral interactions, short-lived, long-lived, rotating, etc) ?
Are you trying to put delivery teams, “virtual” ad-hoc teams, guilds/CoPs into the same diagram?
Are you trying to mash reporting hierarchy diagrams to be part of team diagrams?
Is your diagram a reflection of “As-is” (status-quo today), or “To-be” (to target a desirable team topology), or “transitional” (some middle-step to bridge the two)?
Is your diagram stating what is actually happening or what hypothetically interactions should happen (but probably don’t the way you would prefer )?
Do you keep people with the best information about different parts of the diagram involved in creating those parts of your diagram?
Are you the only person (or part of a small group of people who do not represent the actual teams) informing what the teams, interactions, and capabilities of teams are on the diagram?
Does this diagram help my audience explore what is important to discuss?
Is it clear where handovers are along the flow of value (or change)?
Is it clear what each type of team and interaction is?
Is it clear which teams are heavily involved with interactions?
Is it clear and worth showing which teams have different amounts of intrinsic cognitive load? (Usually done by adding detail about what capabilities they have)
Is everyone thinking about the teams and avoiding discussions about the interactions?
Is the diagram obscuring something that is core to the problems we have, such as not showing handovers between teams during the flow of value from left to right? Remember, your diagram should be a focused extraction of the model, not a pleasant distortion of it.
More than half of these questions come from simply taking Team Topology and freedom to re-imagine things that Simon Brown of C4 fame has talked or written about for software architecture diagrams. I think the advice is really well ported to this ecosystem, and I hope you find this lens as useful as I do too.
Regardless of how you use diagrams, the most important thing to keep in mind and communicate to people who you use diagrams with is: The diagram is not the model, it is a way to frame part of the the model and still surface a meaningful, focused, and useful conversation. Team Topology diagrams are meant to drive valuable conversations that result in organizations making changes that result in Fast-Flow. They are not meant to archive and document every intricate nuance imaginable, as that wouldn’t be a worthwhile diagram to guide conversations with, but we do need to deepen our own understanding to create those meaningful diagrams anyway.