August 2026 Summaries

CLAUDE.md is a concise, project-specific Markdown file that gives Anthropic’s Claude Code persistent instructions for working accurately with an API, reducing reliance on stale training data or inferred documentation. API documentation teams can include it in public SDKs, starter kits, and sample applications to define the API’s purpose, authentication requirements, authoritative documentation sources, common errors, and implementation conventions such as pagination, idempotency, versioning, and field naming. The file should generally remain under 200 lines, link to rather than duplicate OpenAPI specifications and reference documentation, and be maintained through Git reviews, release-cycle checks, periodic audits, and feedback from recurring developer issues. CLAUDE.md complements rather than replaces OpenAPI specifications, while LLMs.txt helps AI tools navigate hosted documentation and AGENTS.md provides similar cross-tool guidance. ReadMe’s LLMs.txt, MCP server, AI-assisted documentation tools, and structured OpenAPI support can help Claude retrieve current API schemas and documentation rather than relying on scraped or outdated sources.

Model Context Protocol (MCP) is a standard introduced by Anthropic that lets AI agents connect to external systems such as APIs, databases, documentation, code hosts, and messaging platforms through discoverable tools with defined schemas. Unlike traditional APIs, which require callers to already understand available endpoints and parameters, MCP enables agents to inspect capabilities, search for relevant information, and execute actions through a consistent request-response process. For API documentation, an MCP server can expose OpenAPI-based tools for listing and searching endpoints, retrieving endpoint details, and making live requests, allowing assistants to access current documentation selectively rather than relying on stale exports or training data. The approach can improve developer workflows, reduce documentation-related support requests, and provide more accurate API guidance, while authentication can separately control access to documentation and live API calls. Building such a server independently requires ongoing engineering for protocol support, search, synchronization, and authentication, whereas ReadMe offers a managed option that generates an MCP server from an existing API specification, supports endpoint controls and custom tools, forwards user credentials for API requests, and provides analytics on agent usage.

Technical writers contribute institutional knowledge, product-testing experience, and user understanding that generative AI cannot fully replace, but AI can supplement documentation workflows when used thoughtfully. The first installment of a three-part series focuses on improving documentation search and discoverability, areas where AI performs well by summarizing, structuring, and retrieving information across large bodies of content. It recommends AI-powered documentation search tools such as ReadMe’s Ask AI, which can be trained on a company’s content, configured for tone, detail, models, and restricted topics, and monitored through question and response analytics. The piece also emphasizes making documentation accessible to AI systems through agent-friendly features such as LLMs.txt files, link headers, agent skills, and direct MCP server connections for coding tools, helping those tools use accurate API details rather than inferred information.

Effective API documentation should be designed around developers’ tasks and likely points of confusion rather than the assumptions of the teams that built the API. The piece highlights five core documentation types: API references, exemplified by Socure’s plain-language endpoint descriptions, workflow-specific schemas, and multi-language code samples; getting-started guides, such as Gusto’s chronological setup instructions, expected responses, and deeper links; tutorials, like Clever’s OAuth walkthrough, which foregrounds prerequisites, expected results, and common pitfalls; changelogs, illustrated by Doppler’s concise, audience-specific explanations of capabilities and links to details; and developer guides, such as Samsara’s full resource lifecycle coverage, permissions, sample requests and responses, and unexpected API behaviors. Across these formats, useful practices include clear language, copy-ready examples, visible outcomes, proactive troubleshooting, and regularly updated content. The article also presents ReadMe as a platform for producing interactive API documentation, automatically generating references, auditing quality, and helping documentation stay aligned with code changes, citing customer outcomes including reduced onboarding time and support tickets.