Documentation

API documentation is the single most important factor in whether an API succeeds, and I have believed this since the very beginning. It was one of the first things I wrote about when I started API Evangelist in 2010, and fifteen years and several documentation revolutions later, I have never wavered: documentation is where adoption is won or lost. You can have the most elegant, powerful, well-designed API in the world, and if the documentation is bad, nobody will use it. Conversely, a fairly ordinary API with exceptional documentation will outperform its betters every time. Documentation is the interface between your API and the human being trying to understand it, and that interface is where the entire relationship begins. Everything else — the technology, the business model, the evangelism — depends on a developer first being able to understand what your API does and how to use it.

Why we write documentation is a question I took on directly in 2012, because I wanted to push past the checkbox mentality. Too many providers treated documentation as an obligation — something you produce because you’re supposed to, a static reference dumped onto a page and forgotten. But documentation isn’t a deliverable, it’s a conversation. It’s how you communicate your API’s purpose, its capabilities, its constraints, and its personality to the people you need to reach. Good documentation anticipates the developer’s questions, meets them where they are, and walks them from curiosity to their first successful API call as quickly as possible. The reason we write documentation is to make a developer successful, and every documentation decision should be measured against that goal. I called documentation an error-bridging artifact in 2014 — the bridge between where the API actually is and where the developer needs to be — and the quality of that bridge determines whether they make the crossing.

The history of API documentation is really a history of three or four distinct eras, and I’ve lived through all of them. The first era was static, hand-written reference documentation — prose on a web page describing endpoints, parameters, and responses, maintained by hand and perpetually out of date. Then came the first interactive revolution. Mashery open-sourced their I/O Docs in 2011, one of the earliest tools that let developers actually make live API calls from within the documentation itself, and that was a genuine breakthrough — documentation you could touch and execute rather than just read. The real turning point, though, was Swagger UI. When Swagger UI arrived, it changed everything, because it generated interactive, explorable documentation directly from a machine-readable API definition. I wrote in 2016 about learning from the success of Swagger UI, and the lesson was profound: the most successful documentation tool in history succeeded because it was generated from a definition, which meant the docs stayed in sync with the API, and because it let developers explore and execute right there on the page. Swagger UI did more to advance API documentation than any amount of writing advice ever could, because it solved the synchronization problem and the interactivity problem at the same time.

The machine-readable insight is the one I want to emphasize most, because it’s the through-line of the entire modern documentation story. The single most important shift in API documentation was the move from hand-maintained docs to documentation generated from a machine-readable definition — OpenAPI, formerly Swagger. Once your documentation is generated from your OpenAPI contract, the docs can’t drift out of sync with the API, because they’re derived from the same source of truth. I argued in 2015, when the beautiful Slate documentation style was sweeping the industry, that we should be generating Slate from Swagger so we maintain a machine-readable core — because the gorgeous three-column docs that Stripe popularized were worth nothing if they were hand-maintained and immediately stale. The lesson recurred constantly: whatever documentation experience you want to present, generate it from the definition. Dwolla’s use of Slate in 2014 for an evolved documentation experience, Stripe’s interactive walkthrough that I admired in 2016, Redoc’s clean OpenAPI-driven docs in 2017 — the best documentation of the era all shared a common foundation in machine-readable definitions, even when they presented radically different experiences on the surface.

The Stripe documentation became the gold standard that the entire industry chased, and for good reason. Stripe’s three-column layout — narrative explanation on the left, reference in the middle, runnable code samples on the right, all flowing together — set a bar for what developers came to expect. I wrote about digging Stripe’s interactive documentation walkthrough in 2016 because they had cracked something important: documentation that taught rather than just referenced, that held your hand through real use cases with real code, that made the developer feel guided rather than abandoned. Stripe proved that documentation could be a competitive advantage, that investing seriously in the documentation experience paid for itself in adoption. Every developer-focused company since has measured itself, consciously or not, against the Stripe documentation standard.

The democratization of good documentation came through tooling, and I tracked that whole ecosystem as it matured. The vision I kept articulating — someone please build my open, interactive, portable, visual documentation toolkit — gradually got built. ReadMe brought clean, modern, managed documentation portals. Redoc brought beautiful open-source OpenAPI-driven docs. Stoplight displayed definitions by default. And the minimum viable documentation movement, which I pushed hard around 2017 and 2018 with forkable Jekyll templates and blueprints, was about lowering the barrier — giving teams a baseline, executable, definition-driven documentation example they could fork and run, so that good documentation stopped being something only well-resourced companies could afford. Documentation belongs in the API lifecycle as a first-class concern, as I laid out in the lifecycle basics, generated and maintained alongside the API itself rather than bolted on at the end by a separate team working from stale information.

Documentation has never been just reference material, and the explorer thread is part of why. I wrote in 2011 about how API explorers open API access beyond developers — the Google and Facebook Graph API explorers let non-programmers poke at an API and understand it without writing code. This matters because documentation’s audience has always been broader than just the integrating developer. Code samples are documentation too — I wrote in 2011 about claiming your territory with new APIs by building code samples, because the sample is often the first thing a developer copies, and the language coverage of your samples signals who you think your audience is. The modern documentation experience, as I described it in 2025, is an intersection of static docs, interactive docs, explorers, and API clients — these are not separate things but a continuum, and the best developer experiences blend them so that reading, exploring, and executing flow into one another. Every modern API, I argued, should have an OpenAPI definition, JSON Schema, and interactive documentation as the baseline — not as a premium feature but as table stakes.

Now we are in what I’ve called the third API documentation renaissance, and it’s being driven by AI. I wrote in 2025 that we’re entering this third renaissance, and the forcing function is that documentation now has two audiences: humans and machines. For fifteen years documentation was about making an API understandable to a human developer. Now it also has to make the API understandable to an LLM, a copilot, or an AI agent — and I wrote in 2024 about moving API docs from human-readable to machine-readable precisely because the AI consumer parses structured, consistent, machine-readable documentation far better than it parses narrative prose. This is both a challenge and a vindication: the machine-readable foundation I’ve been advocating for since the Swagger days turns out to be exactly what AI needs. The 2026 work on building a bridge between human and AI on your documentation — where a developer can open your docs directly in Claude or ChatGPT via MCP — is the leading edge of this. Documentation is becoming a dual-audience artifact, and the providers who built on clean machine-readable definitions are positioned to serve both audiences while the ones who hand-wrote HTML are scrambling. The new generation of tools like Scalar, and the developer-experience focus at companies like Redocly, are building for exactly this moment.

The throughline across every era is that documentation is the developer experience made concrete, and that the machine-readable definition is the foundation under all of it. From hand-written reference pages, through the Swagger UI and Slate and Stripe revolutions, to the minimum-viable-docs democratization, to the AI-driven third renaissance — the constant has been that documentation determines adoption, and that documentation generated from a definition beats documentation maintained by hand. A developer portal, or the lack of one, tells you almost everything about how an enterprise thinks about its APIs, as I wrote in 2024 — it’s the most honest signal of whether a company actually cares about the people consuming its capabilities. Documentation is where you prove that you’ve thought about the developer, the consumer, and now the agent on the other side of your API. It always has been the most important thing, and as the audience expands to include machines, it has only become more important, not less.

Guidance

API Learnings

APIs

API Governance

API Solutions

API Discovery

API Building Blocks

API Evangelist LLC

Documentation

References

Guidance Details

Explore more

Discover APIs