In Manuel Pais and Matthew Skelton’s book Team Topologies: Organizing Business and Technology Teams for Fast Flow, they mention a concept which can potentially be quite powerful for Agile teams in general – the “Team API.”
Here is how Pais & Skelton define it:
With stable, long-lived teams that own specific bits of the software systems, we can begin to build a stable team API: an API surrounding each team. An API (Application Programming Interface) is a description and a specification for how to interact programmatically with software, so we extend this idea to entire interactions with the team.
Note: We’re using the term “API” differently from in the conventional, technical sense (Application Programming Interface). Here we’re using the term to signify that we can create patterns for the ways in which a team communicates, outside of code, both internally and externally. For instance, we can do this by setting up a team space in Confluence, which has a particular structure, which makes it easier to find information about what the team is working on, and similar topics.
The primary benefit of a Team API, for multiple teams that work together or need things from one another, is analogous to the benefit of having a Team Working Agreement for a single team. A single team can benefit from writing down their thoughts on how they can best collaborate. A team API makes it easier for teams to collaborate, because they have a certain set of pattern-driven expectations about where to find information about what the other teams are doing.
Agreeing to a Team API can be helpful in many situations, such as the following:
Simply stated, a Team API can include:
In other words, the Team API consists of “just enough” documentation to describe the why, what, and how associated with the work that the team does. The choice of the word “can” in the sentence above is important, because we want to avoid being overly prescriptive (giving teams flexibility in terms of the level of detail), while at the same time identifying a baseline set of expectations in terms of topics that each Team API ideally covers. That is, we want the Information Architecture (content structure) that the team uses, in Confluence for example, to be reasonably consistent from one team to the next, to make it easier for teams to “consume” the information from each other.
The short answer to this question is “no.” It is perfectly fine to provide links to code repositories, Swagger documentation, and so on. An important consideration is having some level of consistency when it comes to where in the Team API hierarchy these types of links to artifacts can be found.
Keeping in mind that the areas needing coverage could vary, depending on team context, below is a list of topics that potentially can be included in a Team API. Thus, to prepare for a session where a Team API is to be created, it will be necessary to know where these types of things are located:
Pais and Skelton provide the following additional observations about Team APIs:
The Team API should explicitly consider usability by other teams: Will other teams find it easy and straightforward to interact with us, or will it be difficult and confusing? How easy will it be for a new team to get on board with our code and working practices? How do we respond to pull requests and other suggestions from other teams? Is our team backlog and product roadmap easily visible and understandable by other teams?
For effective team-first ownership of software, teams need to continuously define, advertise, test, and evolve their Team API to ensure that it is fit for purpose for the consumers of that API: other teams.