Social Decision Records and Team APIs: Documenting Human Interactions for Better Collaboration

Blog

27 Jun

Written By Team Topologies

Photo by Ann H from Pexels: https://www.pexels.com/photo/sneakers-beside-arrows-2646530/

Key Takeaways

It’s vital to surface and track social decisions within and across teams
Social Decision Records (SDRs) act as a way to build transparency and trust
Combined with the Team API discipline, SDRs are a powerful way to provide greater intentionality around value delivery
SDRs have a similar role to the well-known Architecture Decision Records (ADRs) but for social decisions rather than architectural ones

Introduction

Social Decision Records (SDRs) succinctly record the key elements of a decision taken by a team, capturing the human and managerial aspects of an agreement. They serve as a historical ledger of how and why teams agreed to interact.

To make these agreements visible and actionable, SDRs work perfectly alongside a Team API, a concept from Team Topologies. A Team API is a clear, decentralized interface that describes different aspects related to a team's ownership, communication preferences, and practices. While SDRs document the specific, point-in-time decisions that shape how teams work together, the Team API acts as the living, breathing document that provides visibility to the whole organization regarding a team’s current work and priorities.

Using SDRs and Team APIs together makes a team's purpose inherently clearer. By explicitly defining and publishing how they want to be viewed and how they prefer to interact with others, teams minimize the cognitive load on the rest of the organization. Other teams can quickly find out exactly who they need to talk to, when they should reach out, and through which channels (such as specific chat tools or sync meetings). This deliberate communication reduces interruptions, limits context switching, and builds organizational trust because dependencies are promoted in a healthy, visible way rather than remaining hidden blockers.

Photo by Nothing Ahead from Pexels: https://www.pexels.com/photo/close-up-of-a-man-holding-a-camera-lens-7349278/

SDRs: Structure and Relationship with ADRs

The structure of an SDR intentionally mirrors the structure of an ADR. In practice, the relationship between the two is very strong, and an SDR will often reference an ADR (and vice versa) to tell the complete story of a decision and its expected consequences.

For your SDRs, a simple and effective structure includes the following sections:

Status: DRAFT / PROPOSED / DONE / etc.
Owners: The list of people or teams that have participated in the decision.
Informed: The list of people informed of the decision.
Date: The date that matches the beginning of the current status.
Context: The circumstances under which the decision was taken, addressing why a decision is needed in the first place.
Decision: A clear articulation of the decision taken.
Consequences: An examination of the expected outcomes—both positive and negative—of taking the decision.

Patterns, Examples, and Team API Integrations

You can use an SDR to record almost any managerial or delivery concern in your team. Below are a few common patterns and examples of how these records translate seamlessly into a Team API.

1. Defining Collaboration Between Teams to Deliver a Project

Often, different teams must collaborate to ship a common project, and it is essential to define which team is responsible for specific parts of the development and release process.

SDR Example: Team Monkey needs to work on Team Bear's codebase to deliver "Project Cherry". They write SDR-0100, stating that Team Monkey will be the primary owner and will build the feature with Team Bear's support. The SDR notes that Team Monkey must follow Team Bear's quality strategy, but acknowledges a critical consequence: Team Bear’s overall capacity will be reduced by 30%.
Team API Integration: To make this transparent, Team Bear’s Team API would immediately be updated. Under an "Interactions" or "Teams we currently interact with" section, it would publicly list Team Monkey, state the interaction mode (e.g., Collaboration), note the purpose (Project Cherry), and set the duration of the agreement. Everyone in the organization can now see exactly why Team Bear's capacity is constrained.

2. Team Strategy and Protocols for Collaboration

Sometimes, a team that provides services to many other teams needs to define a strict protocol of collaboration to handle incoming requests efficiently.

SDR Example: Team Wolf owns the main flow of a system and is constantly slowed down by disorganized requests from other teams trying to embed features. They write SDR-0250 to establish a new integration method, deciding that client teams must align features with leadership, create independent components, and get PRs approved by both teams.
Team API Integration: This SDR effectively serves as the foundation for Team Wolf's Team API. By surfacing these rules in their API, Team Wolf can declare their "service level expectations" (such as acknowledging support requests within a specific timeframe) and point clients to dedicated #support or #releases chat channels. Implementing a workflow builder in these channels ensures all requests follow the structure agreed upon in the SDR, allowing Team Wolf to focus on their work without unpredictable interruptions.

Photo by Ekrem KÖSE from Pexels: https://www.pexels.com/photo/ancient-text-in-stone-23938508/

3. Team Restructuring and Temporary Loans

Teams frequently change shape: people are added, removed, loaned out, or entirely merged. When this happens, peers and superiors must understand the new commitments and boundaries.

SDR Example: Because of a lack of new work, Team Koala is being disbanded and its domain, software, and personnel are being merged into Team Panther, a mature but understaffed team. SDR-025 documents this merger, highlighting critical consequences such as increased cognitive overload for Team Panther, a larger surface of risk, and a higher likelihood of production incidents during the transition period.
Team API Integration: Following the merger, Team Panther’s Team API must be updated to reflect its new reality. Their API's "Software owned" and "Wiki search terms" sections will expand to include Team Koala's former components. Furthermore, under the "What we’re currently working on" section of their Team API, Team Panther might publicly state that they are focusing on onboarding and pairing sessions to mitigate the knowledge gap documented in the SDR.

Conclusions

SDRs are an easy, lightweight tool to help you analyze, negotiate, and formally record the decisions of a complex sociotechnical system. They are highly flexible and can be adapted to fit your team's specific people management or delivery concerns.

When combined with the concept of a Team API, SDRs become incredibly powerful. The SDR acts as the negotiated contract, while the Team API acts as the public, easily consumable broadcast of that contract. Together, they bring interactions out of the shadows, clarifying purpose, setting realistic boundaries, and fostering an environment built on genuine transparency and organizational trust.