Project 2: Team Service Interface (The Team README)
Build a standardized “Team API” document that defines how other teams interact with your team—the human and process interface, not just code.
Quick Reference
| Attribute | Value |
|---|---|
| Difficulty | Beginner |
| Time Estimate | Weekend (6-10 hours) |
| Primary Language | Markdown |
| Alternative Languages | HTML, Static Site Generator |
| Prerequisites | Understanding of your team’s responsibilities |
| Key Topics | Team APIs, Information Hiding, Self-Service |
1. Learning Objectives
By completing this project, you will:
- Define your team as a service with explicit inputs and outputs
- Document communication protocols for different request types
- Establish response time expectations (Service Level Expectations)
- Reduce “random questions” that interrupt flow
- Create a template other teams can adopt
2. Theoretical Foundation
2.1 Core Concepts
The Team API
Just as a microservice has an API contract, your team should have a “human API” that defines:
- What services you provide
- How to request those services
- What response times to expect
- What falls outside your scope
TRADITIONAL TEAM TEAM-AS-A-SERVICE
┌─────────────────────┐ ┌─────────────────────────────────┐
│ Random Slack DMs │ │ Defined Intake Channels │
│ Meetings on demand │ │ Async-first communication │
│ Unclear ownership │ => │ Published service catalog │
│ Variable response │ │ SLE commitments │
│ Tribal knowledge │ │ Self-service documentation │
└─────────────────────┘ └─────────────────────────────────┘
Information Hiding (Parnas Principle)
Teams should hide internal implementation details from consumers. Other teams don’t need to know:
- Which specific person handles which task
- What tools you use internally
- How you prioritize your backlog
They only need to know:
- How to reach you (one front door)
- What to expect (response time, quality)
- What you provide (service catalog)
The “Front Door” Pattern
┌───────────────────────────────┐
│ TEAM API │
│ (Single Entry Point) │
└───────────────┬───────────────┘
│
┌───────────────────┼───────────────────┐
│ │ │
▼ ▼ ▼
┌───────────────┐ ┌───────────────┐ ┌───────────────┐
│ #ask-platform │ │ Jira Form │ │ PagerDuty │
│ (General) │ │ (Requests) │ │ (Urgent) │
└───────────────┘ └───────────────┘ └───────────────┘
All requests flow through defined channels. No backdoor DMs to individual engineers.
2.2 Why This Matters
The hidden cost of undefined interfaces:
| Scenario | Without Team API | With Team API |
|---|---|---|
| “Quick question” | 10-minute interruption | Self-service via docs |
| Feature request | DM to random engineer | Ticket with prioritization |
| Urgent issue | Panic in Slack | PagerDuty with clear escalation |
| Onboarding | 2 weeks of shadowing | 1-day self-service |
Studies show that a developer takes 23 minutes to regain focus after an interruption. If your team gets 5 “quick questions” per day, that’s nearly 2 hours of lost productivity—per person, per day.
2.3 Historical Context
The concept of internal service interfaces emerged from:
- DevOps movement (2010s): Teams should own their services end-to-end
- Platform Engineering (2020s): Platform teams serve internal customers
- Team Topologies (2019): Formalized the “Team API” concept
2.4 Common Misconceptions
| Misconception | Reality |
|---|---|
| “Documentation slows us down” | Documentation prevents repeated questions |
| “We’re too small for process” | Process scales; lack of process doesn’t |
| “People will still DM me” | Clear boundaries require enforcement |
| “This is just for platform teams” | Every team is a service provider |
3. Project Specification
3.1 What You Will Build
A TEAM_INTERFACE.md file that lives in every repository owned by your team. When a new developer from another team wants to use your service, they read this file and have everything they need to start—without talking to you.
3.2 Functional Requirements
- Mission Statement
- One-paragraph description of what your team does
- Explicit boundaries (what you DON’T do)
- Service Catalog
- List of every service/tool your team provides
- Link to documentation for each
- Communication Protocols
- General questions: Which Slack channel?
- Feature requests: Which form/ticket system?
- Urgent issues: Which pager/escalation path?
- Feedback: How do you prefer to receive it?
- Service Level Expectations
- Response times for each channel
- Availability hours
- On-call information
- Dependencies & Requirements
- What do you need from consumers? (Auth context, specific formats)
- What do you depend on? (Other teams, external services)
3.3 Non-Functional Requirements
- Must be discoverable (standard location, linked from repo README)
- Must be current (include “last updated” date)
- Must be actionable (every contact should have a link)
- Must be enforced (team actively redirects off-channel requests)
3.4 Example Usage / Output
Complete TEAM_INTERFACE.md:
# Team: Ghostbusters (Infrastructure Platform)
> Last Updated: 2025-01-15 | Owner: @jane-lead
## Our Mission
To provide reliable, self-service compute and storage for application teams.
We reduce the cognitive load on developers so they can focus on business logic,
not infrastructure.
### What We Do
- Kubernetes cluster management
- CI/CD pipeline templates
- Observability stack (Prometheus, Grafana, Loki)
- Cloud account provisioning (AWS, GCP)
### What We Don't Do
- Write application code
- Debug application logic
- Manage team-specific AWS resources (we provide the account, you manage it)
- 24/7 support for non-production environments
---
## How to Reach Us
| Need | Channel | Response Time |
|------|---------|---------------|
| General questions | [#ask-ghostbusters](slack://channel?id=C123) | 4 business hours |
| Feature requests | [Platform Request Form](https://jira.example.com/form/123) | 2 business days triage |
| Bug reports | [Platform Bug Form](https://jira.example.com/form/456) | 1 business day |
| Production emergency | [PagerDuty](https://pagerduty.com/services/789) | 15 minutes |
### When NOT to Contact Us
- Your pod is crashing → Check your logs first, then #ask-ghostbusters
- CI is slow → We'll see it in our metrics; no need to report
- "Quick question" via DM → Post in #ask-ghostbusters (we don't monitor DMs)
---
## Our Services
### 1. Kubernetes Clusters
- **Production**: `prod-useast.k8s.internal`
- **Staging**: `staging.k8s.internal`
- [Full Documentation](https://docs.example.com/k8s)
- [Self-Service Namespace Request](https://jira.example.com/form/ns)
### 2. CI/CD Templates
- [Pipeline Catalog](https://docs.example.com/ci-templates)
- Supported languages: Go, Python, TypeScript
- [Request New Language Support](https://jira.example.com/form/ci-lang)
### 3. Observability
- Dashboards: [Grafana](https://grafana.example.com)
- Logs: [Loki](https://loki.example.com)
- Alerts: [AlertManager](https://am.example.com)
- [How to Add Custom Dashboards](https://docs.example.com/dashboards)
---
## Service Level Expectations
| Service | Availability Target | Support Hours |
|---------|---------------------|---------------|
| Prod Kubernetes | 99.9% | 24/7 |
| Staging Kubernetes | 99% | Business hours |
| CI/CD Pipelines | 99.5% | Business hours |
| Observability | 99% | Business hours |
**On-Call**:
- Primary: Rotating weekly among team members
- Current: Check [PagerDuty Schedule](https://pagerduty.com/schedules/123)
---
## Dependencies
### What We Need From You
- Applications must use our [logging library](https://docs.example.com/logging)
- All services must have health endpoints (`/health`, `/ready`)
- Container images must be in our registry (`registry.example.com`)
### What We Depend On
- AWS (us-east-1, us-west-2)
- [Auth Team](./AUTH_TEAM_INTERFACE.md) for SSO/RBAC
- [Network Team](./NETWORK_TEAM_INTERFACE.md) for VPCs
---
## Team Information
- **Team Lead**: Jane Smith (@jane-lead)
- **Product Manager**: Bob Johnson (@bob-pm)
- **Team Size**: 6 engineers
- **Slack Channel** (internal only): #team-ghostbusters
- **Roadmap**: [Productboard](https://productboard.example.com/ghostbusters)
---
## FAQ
**Q: Can I run Windows containers?**
A: Not currently. File a feature request if you have a business need.
**Q: Why was my request closed?**
A: Check the ticket comments. Common reasons: incomplete info, out of scope.
**Q: How do I get access to production?**
A: [Access Request Form](https://jira.example.com/form/access) - requires manager approval.
3.5 Real World Outcome
After deploying this document:
- “Random questions” in Slack decrease by 60%+
- Average onboarding time for new consumers drops from 2 weeks to 2 days
- Team lead spends 50% less time in “context-sharing” meetings
4. Solution Architecture
4.1 High-Level Design
┌─────────────────────────────────────────────────────────────────┐
│ TEAM INTERFACE SYSTEM │
└─────────────────────────────────────────────────────────────────┘
│
┌─────────────────────┼─────────────────────┐
│ │ │
▼ ▼ ▼
┌───────────────┐ ┌───────────────┐ ┌───────────────┐
│ DISCOVERY │ │ TEMPLATES │ │ ENFORCEMENT │
│ │ │ │ │ │
│ - Repo README │ │ - Base format │ │ - Bot replies │
│ - Backstage │ │ - Required │ │ - Redirect │
│ - Search │ │ sections │ │ policy │
└───────────────┘ └───────────────┘ └───────────────┘
4.2 Key Components
- TEAM_INTERFACE.md: The core document
- Intake Forms: Jira/Linear forms for different request types
- Slack Bot (optional): Auto-responds with relevant docs
- Backstage Integration (optional): Centralized service catalog
4.3 Data Structures
The document itself is the data structure. For automation, you might add frontmatter:
---
team_id: ghostbusters
team_name: Infrastructure Platform
lead: jane-lead
last_updated: 2025-01-15
services:
- name: kubernetes
docs: https://docs.example.com/k8s
status: stable
- name: cicd
docs: https://docs.example.com/ci
status: stable
---
4.4 Algorithm Overview
- Audit current team responsibilities
- Categorize incoming requests from last 30 days
- Draft document covering all categories
- Validate with recent requesters
- Publish in standard location
- Enforce by redirecting off-channel requests
5. Implementation Guide
5.1 Development Environment Setup
No special setup required—you need:
- Markdown editor (VS Code, Obsidian)
- Access to your repo
- Access to Slack/Jira/PagerDuty for links
5.2 Project Structure
your-team-repo/
├── README.md # Links to TEAM_INTERFACE.md
├── TEAM_INTERFACE.md # The main document
└── docs/
├── service-a.md # Detailed docs per service
└── service-b.md
5.3 The Core Question You’re Answering
“Can a stranger use your team’s services without ever speaking to you?”
If the answer is “No,” you have a high-coordination operating model. High-performing organizations strive for “X-as-a-Service” where the interface is documented and self-contained.
5.4 Concepts You Must Understand First
Stop and research these before writing:
- Information Hiding
- What internal details should stay hidden from outside?
- Book Reference: “A Philosophy of Software Design” by John Ousterhout
- The “Team API” Concept
- What are the components of a team’s public interface?
- Book Reference: “Team Topologies” Ch. 6
- Self-Service Principles
- Why is “self-service” more scalable than “high-touch”?
- Reference: Platform Engineering community resources
5.5 Questions to Guide Your Design
Before writing, think through these:
Accessibility
- Where should this document live so it’s easily found?
- Should it be in the repo, a wiki, or both?
- How do you keep it from going out of date?
Scope
- If someone asks for something “Out of Scope,” how does the document handle that?
- Does the document include “On-call” details?
- Should you include team internal processes (probably not)?
Enforcement
- What happens when someone ignores the interface and DMs you directly?
- How do you train the organization to use the interface?
5.6 Thinking Exercise
The “New Hire” Experiment
Imagine a new hire starts in a different department. They are told they need to integrate with your system.
Questions while analyzing:
- What are the first 5 questions they will ask?
- Are all 5 of those questions answered in your README?
- If not, your interface has a “leak.”
Exercise:
- Write down the 5 questions
- For each, note where (if anywhere) they’d find the answer today
- Mark gaps for your TEAM_INTERFACE.md
5.7 Hints in Layers
Hint 1: Start with the Catalog List every service, tool, or process your team owns. Don’t overthink—just list.
Hint 2: Define the Front Door Decide on exactly ONE way for people to ask for new things. Is it a Jira form? A specific Slack channel? Close all other doors.
Hint 3: Add Service Expectations Don’t just say “we help.” Say “we respond to tickets in 48 hours and we only support Python 3.9+.”
Hint 4: Make it a Template Don’t just write one. Write a template so every team in the company can have the same structure.
5.8 The Interview Questions They’ll Ask
Prepare to answer these:
- “What makes a ‘good’ team interface?”
- Clear scope, explicit response times, self-service when possible
- “How do you handle requests that fall outside your team’s defined scope?”
- Document the boundary, redirect politely, track frequency of out-of-scope requests
- “Why is documentation considered part of the ‘Team API’?”
- Documentation IS the interface for self-service
- “How do you balance ‘self-service’ with the need for security/compliance?”
- Self-service with guardrails (automated checks, mandatory fields)
- “What do you do if another team ignores your interface and DMs your devs?”
- Politely redirect with link to interface, track violations, escalate if persistent
5.9 Books That Will Help
| Topic | Book | Chapter |
|---|---|---|
| Team APIs | “Team Topologies” by Skelton & Pais | Ch. 6: Choose Team Interaction Modes |
| Interface Design | “A Philosophy of Software Design” by Ousterhout | Ch. 4: Modules Should Be Deep |
| Self-Service | Various Platform Engineering articles | - |
5.10 Implementation Phases
Phase 1: Audit (2 hours)
- List all services your team owns
- Review Slack history for last 30 days: What do people ask?
- Categorize requests: General / Feature / Bug / Urgent
Phase 2: Draft (2-3 hours)
- Write mission statement
- Create service catalog table
- Define communication channels for each category
- Add response time expectations
Phase 3: Validate (1-2 hours)
- Share draft with 2-3 frequent requesters
- Ask: “Would this have answered your questions?”
- Incorporate feedback
Phase 4: Publish & Announce (1 hour)
- Add to repo
- Link from main README
- Announce in relevant Slack channels
- Set reminder to review monthly
5.11 Key Implementation Decisions
| Decision | Option A | Option B | Recommendation |
|---|---|---|---|
| Location | Repo root | Wiki | Repo root (version controlled) |
| Format | Plain Markdown | With frontmatter | Frontmatter if using Backstage |
| Detail level | High-level only | Every edge case | Start high-level, add as questions arise |
| On-call info | Include | Separate doc | Include basic, link to detailed |
6. Testing Strategy
Validation Tests
- Show to 3 people outside your team
- Ask them to find: How to request a new feature, who to call for urgent issue
- Time how long it takes
Completeness Tests
- Review last 10 Slack questions to your team
- Verify each is answered in the document
Freshness Tests
- Schedule monthly review
- Check all links still work
- Verify contact names are current
7. Common Pitfalls & Debugging
| Problem | Symptom | Root Cause | Fix |
|---|---|---|---|
| Nobody reads it | Same questions keep coming | Not discoverable | Add to repo README, Backstage, Slack topic |
| Out of date | Wrong links, old names | No maintenance process | Monthly review calendar invite |
| Too detailed | People skim and miss key info | Tried to document everything | Move details to linked pages |
| Not enforced | People still DM | No redirect habit | Consistently reply “Please post in #channel” |
8. Extensions & Challenges
Extension 1: Slack Bot Integration
Create a Slackbot that auto-replies when someone posts in #ask-yourteam with relevant doc links.
Extension 2: Intake Form Automation
Build a Jira form that validates required fields and routes to the right team member.
Extension 3: SLE Dashboard
Create a Grafana dashboard showing actual response times vs. SLE targets.
Extension 4: Cross-Team Template
Package your format as a template. Present to engineering leadership for org-wide adoption.
9. Real-World Connections
How Big Tech Does This:
- Spotify: Every squad has a “squad health check” and public interface
- Google: Internal services have formal “Service Owners” with SLOs
- Netflix: Extensive internal documentation culture
Tools That Formalize This:
- Backstage.io: Service catalog with Team API concept built-in
- Notion/Confluence: Often used for team wikis
- Opslevel: Service ownership and maturity tracking
10. Resources
Templates
Articles
Related Projects
- P01: Team Interaction Audit - Map how teams talk today
- P07: SLE Agreement - Formalize response expectations
11. Self-Assessment Checklist
Before considering this project complete, verify:
- I can explain what a “Team API” is in one sentence
- My document has a clear mission statement
- All services are listed with links to docs
- There’s exactly ONE channel for each request type
- Response time expectations are explicit
- At least 2 external consumers have validated the document
- The document is linked from the repo README
- I have a plan for keeping it updated
12. Submission / Completion Criteria
This project is complete when you have:
- TEAM_INTERFACE.md in your team’s primary repo
- README.md updated to link to the interface
- Validation from at least 2 consumers outside your team
- Announcement in relevant Slack channels
- Calendar reminder for monthly review
Previous Project: P01: Team Interaction Audit Next Project: P03: Ownership Boundary Mapper