A framework for docs teams to define how other teams work with them. Based on the concept of a "team API," this framework makes implicit collaboration patterns explicit by defining input contracts, output contracts, SLAs, and error handling.
You can adapt this framework for other types of teams beyond docs teams.
A team API is a documented interface that defines how other teams interact with your team. It specifies:
- Input contracts: What information you need to do your work.
- Output contracts: What you deliver and in what form.
- SLAs: Expected timelines and response times.
- Error handling: What happens when things don't go as planned.
The goal is to make collaboration patterns explicit, reducing friction and misunderstandings.
For more information, check out what's a team API?.
Docs teams often struggle with:
- Requests that lack necessary information
- Unclear expectations about timelines
- Last-minute changes that derail planning
- Ambiguity about who is responsible for what
This framework addresses these challenges by providing:
- Clear requirements for documentation requests
- A complexity framework for realistic timeline planning
- Protocols for handling changes and exceptions
- RACI matrices that clarify responsibilities
This framework is designed for organizations with specific structures and practices. Before adopting it, consider whether your context aligns with these prerequisites and assumptions.
Your organization should have these basic structures in place before adopting this framework.
This framework assumes you have:
- A docs team or dedicated documentation function
- A product development process with defined releases or launches
- Cross-functional collaboration mechanisms (meetings, Slack channels, planning sessions)
- A work tracking system (epics, issues, tickets, or similar)
These are the working assumptions that inform the framework's structure and processes.
The framework is built on these assumptions:
- Planning happens in cycles (quarterly, monthly, or similar periods)
- Product managers own feature launches and coordinate cross-functional work
- Documentation is required for customer-facing changes
- Technical writers review and edit documentation (not just write from scratch)
- Teams have regular touchpoints for planning and coordination
Consider whether significant adaptation is needed before implementing this framework in your organization.
This framework may require significant adaptation if your organization has:
- Very small teams where individuals wear multiple hats
- No dedicated documentation resources
- Fully async teams with no synchronous touchpoints
- Continuous deployment without discrete launches or releases
- Ad hoc processes without formal planning cycles
The framework can be adapted for different contexts by modifying roles, timelines, and processes to match your organizational reality. Start with the pieces that provide the most value and evolve from there.
Navigate the framework documentation organized by category: core framework documents, templates, and examples.
| Document | Description |
|---|---|
| Overview | Main framework document defining how teams work with docs. |
| What's a team API? | Explains the Team API concept and its benefits. |
| Intake process | How documentation requests enter the system. |
| Timeline | Milestone relationships from planning to launch. |
| Complexity framework | Low, medium, high estimation patterns for timeline planning. |
| Documentation plan | What requesters must provide in their documentation plan. |
| Writer assignment | How writers get assigned to projects. |
| Minimum requirements | Prerequisites for writer assignment. |
| Last-minute changes | Protocol for handling changes after cut-off dates. |
| RACI matrix | Responsibility assignments for launch activities. |
| Glossary | Shared terminology definitions. |
| Feature documentation | Requirements for documenting features. |
Ready-to-use templates for implementing the framework in your organization.
| Template | Description |
|---|---|
| Overview template | Template for team API overview documents. |
| Intake template | Template for documentation intake requests. |
| Timeline template | Template for milestone timelines. |
| Complexity framework template | Template for complexity assessment criteria. |
| Documentation plan | Fill-in template for documentation plans. |
| Writer assignment template | Template for writer assignment processes. |
| Minimum requirements template | Template for intake prerequisites. |
| RACI template | Blank RACI for customization. |
| Glossary template | Template for terminology definitions. |
| Feature documentation template | Template for feature documentation requirements. |
Sample implementations showing how the framework works in practice.
| Example | Description |
|---|---|
| Sample overview | Sample team API overview document. |
| Sample intake | Completed intake for a fictional feature. |
| Sample intake (high complexity) | Completed intake for a fictional high-complexity feature introducing a new syntax and multi-system coordination. |
| Sample intake process | Detailed intake process example with variations and customization notes. |
| Sample timeline | Timeline diagram and milestone descriptions for a medium-complexity feature. |
| Sample complexity framework | Example complexity assessment framework with three tiers. |
| Sample documentation plan | Completed documentation plan for a fictional feature. |
| Sample writer assignment | Writer assignment process example with planning cycle management. |
| Sample minimum requirements | Example of minimum requirements checklist for project intake. |
| Sample last-minute change | Complete last-minute change scenario from notification through resolution. |
| Sample last-minute changes | Protocol document for handling late changes. |
| Sample RACI | RACI adapted for a support team. |
| Sample feature documentation | Example feature documentation requirements and standards. |
| Sample glossary | Sample glossary with common documentation process terms. |
This framework is designed to be customized to fit your organization's specific tools, roles, and processes.
Key areas to adapt:
The framework references generic concepts like "project tracker" and "communication channels." Replace these with your specific tools:
- Project tracker: Jira, Linear, Asana, GitHub Issues, and others
- Communication channels: Slack, Teams, Discord, and others
- Project documents: Google Docs, Notion, Confluence, and others
The framework uses common roles like product manager, engineering manager, and technical writer. Map these to your organization's titles and responsibilities.
The complexity framework provides baseline timelines. Adjust these based on your team's capacity, typical workload, and organizational velocity.
The RACI matrix and intake process reflect one approach. Modify phases, activities, and responsibilities to match how your organization actually works.
See CONTRIBUTING.md for guidelines on improving this framework.
This framework is available under the MIT License. See LICENSE for details.