# Why Stripe Cut 500,000 Internal Docs Down to 5,000?

## Executive summary

The shift in documentation requirements due to AI agents necessitates a fundamental overhaul of technical writing practices. Speakers argue that documentation must be optimized for two distinct audiences: humans (who require visualization, high-level context, and an empathetic user experience) and AI agents (which require pure, machine-readable formats like Markdown). Key strategies include implementing rigorous decision records, drastically reducing documentation bloat (e.g., Stripe's reduction from 500,000 to 5,000 docs), and establishing clear ownership and accountability for documentation quality to prevent production incidents.

## Key takeaways

- Agent vs. Human Documentation Needs: Humans require visual aids and high-level context (the 'big picture'), while AI agents are best served by pure, endless amounts of Markdown, as they process text efficiently and lack the human need for visual cues.
- The Value of Decision Records: Implementing decision records (ADRs) that capture the rationale, decision-makers, and pros/cons of engineering choices provides a critical audit trail. This prevents agents from making assumptions or reverting to outdated practices.
- Documentation Bloat and Cleanup: Organizations often suffer from massive amounts of stale, outdated, or redundant documentation (estimated at 95% of content). Cleaning up this bloat is critical for improving search relevance and agent performance.
- Accountability and Ownership: The industry trend is moving toward assigning explicit ownership of documentation sets (e.g., 'I own reliability'). This shifts responsibility from the AI model to the human team, forcing greater rigor in documentation maintenance.

## Technical details

- Stripe Documentation Reduction: Stripe successfully reduced its internal documentation from approximately 500,000 documents down to 5,000 worth maintaining, demonstrating a scalable approach to documentation governance.
- Agent Context Handling: AI agents can struggle with outdated information because they may 'lean on their biases' or pre-existing training data, ignoring the most current instructions on a page. This requires prompt injection techniques to enforce adherence to the latest source material.
- Optimal Documentation Format: For agents, the ideal format is pure Markdown, as it allows the agent to read every character and context point. For humans, the format should prioritize visuals and high-level summaries.
- Process Documentation: The use of flowcharts and diagrams is highly effective for conveying complex processes (like a software development lifecycle) compared to lengthy, text-heavy documents.

## Practical implications

- Implement a formal process for capturing and maintaining Decision Records (ADRs) to track the rationale behind architectural choices.
- Treat documentation as a core product component, requiring dedicated resources for maintenance and quality assurance.
- Audit existing documentation repositories to identify and eliminate stale, redundant, or deprecated content.
- Structure documentation using a mix of pure Markdown for machine consumption and visual/diagrammatic elements for human readers.

## Topics

Technical Documentation, AI Agents, Information Architecture, Software Engineering Process, Knowledge Management, Stripe, Falconer, Documentation for Developers, Vercel

Source: https://www.youtube.com/watch?v=btsbU79zuWg
