Note to Audience: This is a post I wrote originally in Confluence. I will protect names and references to past companies. Since I’ve moved most of my writing to SeedTheWay on Substack, this is more a post for me to track topics I’ve written in the past.
Last week all of the Engineering Managers, Directors and our departmental business partners met for a multi-day summit in sunny Denver, Colorado. It was my first chance in my 12+ months here at XYZ Company to call a summit with the Engineering Management team. In past companies, I would try to have a summit or two per year. Working remote and distributed across time zones is an awesome experience, but nothing replaces the tactile feeling of high-fiving a teammate in a conference room or breaking bread at the dinner table.
Our focus on day 1 was 100% on the book Team Topologies. I mentioned the book a while back in a blog hoping it would inspire a number of you to add it to your reading list. I was pleasantly surprised the last few weeks when I learned that a number of team members had picked-up the book and started reading it. I will reiterate to any member of the Engineering team that you can expense the book. It’s essential to our growth and development as a team.
One of the most important exercises we accomplished during the summit was each Pod/Team wrote a draft Team API. The authors of Team Topologies created some sample templates, which they published to GitHub. They happened to make a Team API template. We’ve borrowed the template and created a Confluence Version that teams can easily extend and publish in their team space. I’m looking for all of the Pods/Teams to begin the journey of writing and maintaining a living Team API. First, let’s talk about the Team API to give you some context.
Here’s a great cheat sheet on Team Topologies.
What Is This Team API All About?
I joked with the team that the first 4x I read Team Topologies (I’ve read or listened to it 10x in the last 2+ years), I didn’t pick-up on the idea that a team could/should publish an API so that other teams and members of the current team could understand team dependencies. The Team API encourages the team to make their dependencies (upwards, sideways and downwards) visible, in an easy to consume method.
It’s simply a matter of fact that our Pods/Teams work across teams. We encounter issues such as communication challenges, scheduling issues and prioritization problems when 2 teams are working with each other. It’s often not intentional, but rather a matter of awareness that one team has a dependency on another.
The Team API gives each team a living document with the intent of defining and surfacing the dependencies between teams. There is a mutability that must exist in each Team’s API given that our work changes, evolves and matures over time. The nature of our relationships across teams will change, hopefully for the better in a more self-service way. Also, new teams will be introduced and we must consider that responsibilities and ownership may change over time as well.
I like to think of the Team API equivalently to my personal ReadMe. A good TeamAPI helps internal and external members understand the best way to communicate with the team. The focus and areas of ownership are defined, thus minimizing the need to decode the team’s goals and purpose.
A Note About Living Documents
We’ve all had a lot of enthusiasm to write a document only to find it sits on the shelf collecting dust. When I look in my shelf of living documents, I basically have two that I maintain. My professional ReadMe is a document I try to maintain every few months or 1x a year if something changes. The other document is my Last Will and Testament, which frankly I don’t update much at all.
Living documents are really hard to maintain. The team has to be conditioned and empowered to maintain them. Ultimately, it means the documents have to be considered 1st class citizens. You should share it often. You should refer to it constantly. Members of the team should be trusted to maintain it and update it. It is a team document, hence the team needs to update it.
Think of it like a README in a GitHub repository for a product or artifact. You want your consumers of the repository to be self-sufficient making use of the repository. The README needs to be accurate, informative, simple and “just works”.
So What Goes in the Team API?
An effective Team API will consist of three informational sections that consumers (internal or external) will benefit from reading. The first section is a metadata about the team’s overview and communication attributes. The second section focuses on the the current work of the team. The third section is a small dependency map of teams that the current team interfaces with. I will cover each section in greater detail.
Section One: Team Overview and Communication
The opening section of the Team API helps the reader understand the purpose of the team and their role in the product. The area of focus should be descriptive and obvious that an outsider consumer of the API will understand the core focus of this team.
Team Topologies introduces 4 types of teams: Stream-Aligned, Platform, Enabling and Complicated Sub-Systems. The vast majority of our teams are Stream Aligned, with a healthy group of Enabling and Platform teams. As of right now, we have not identified a complicated sub-system team in our present topologies. We may down the line, but for now we have not identified any. It’s important that each team represent their topology for what it is in the present time. Below is a quick summary of each topology.
The other meta-data about the team such as versioning, service level, search terms, schedule and chat channels are pretty self-explanatory. I will say it only is self-explanatory if you include and maintain the level of information necessary so that a new consumer or an outside consumer can easily understand without having to have a 1:1 with a member of the team to go over the API. That’s the true litmus test of the Team API.
Section Two: Current Work of a Pod/Team
Interesting enough, I believe the template the authors made should probably retitle this section as the “Current Area of Focus for the Pod”. Often teams have legacy responsibilities that are tied or bound to the team, but they have no efforts or initiatives focused on those legacy areas. I gather the authors are suggesting that teams surface the current work. Needless to say, these three questions are incredibly important. Some teams may even have additional sub-documents that are maintained as living documents. For example, the Cephalopods maintain this Ways of Working document.
Section Three: Lightweight Dependency Map
The authors of Team Topologies introduced another template called a Team Dependency Tracker. In our workshop, we opted to have teams write this small table in as a lightweight exercise. We had originally anticipated performing a small exercise on writing dependencies (incoming and outgoing). We settled on simply writing them in the Team API.
As you can see from the table below, the goal of this section is to define the relationships of interactions between teams. Most teams took the perspective of teams they depend on. However, if your are aware that other teams depend on you, you should identify that relationship in the table. It’s essential to understand the Interaction Mode (Collaborative, X-As-Service or Facilitating).
Seven Seconds 