API Documentation: Teaching, Not Just Listing
In a recent exchange with a service provider about a particularly tricky aspect of their API, the support team offered a familiar but unsatisfying answer: you’ll understand it once you’ve used it for a while. In other words, you’ll only get it after you already get it. That response highlights a common failure mode in technical writing—one that separates reference manuals from genuinely useful documentation.
The goal for most developers picking up a new API isn’t to become an expert overnight. It’s to move from unproductive newcomer to functional practitioner as quickly as possible. That requires grasping the mental model behind the API—the set of concepts and intentions that explain why the system works the way it does. Without that, even a perfectly accurate reference is just a pile of disconnected endpoints.
Writing documentation that conveys that model is genuinely difficult. The same author spent considerable time on Explain the Cloud Like I'm 10 simply to communicate the mental model behind cloud computing. It’s a real craft.
That effort points to a useful distinction between two documentation styles: Euclidean and Socratic.
Euclidean: The Axiom Approach
Euclidean documentation states its axioms and lets the user derive the rest. It’s the easiest style for the API provider to produce and the hardest for the user to absorb. This is, unfortunately, the most common form of API documentation—each endpoint gets a page, but nothing ties the whole system together. Users are left hoping that someone on a forum has already asked and answered the questions they have, before the thread gets buried.
The label comes from mathematics, and the metaphor is apt: Euclid derives a rich geometric system from a small set of axioms, but he never bothers to define primitive terms like “point.” He uses the notion in the axioms, and it’s only through investigating the axioms that you start to understand what a point really is—by seeing the role it plays in the system.
Socratic: From Axioms to Understanding
Socratic documentation does more. It includes the Euclidean reference material, but adds an open inquiry into the user’s understanding—FAQs, recipes for common tasks, error conditions with possible responses, and working code examples. Crucially, it also explains what the API is trying to accomplish and how you can use it to achieve your own goals.
Too often, providers think that publishing a sample on a code-sharing site fulfills the Socratic duty. It doesn’t. The person who wrote the example already knows the mental model. The real job is to communicate that underlying knowledge, not just the end product—to help people reach the point where they could write the example code themselves.
This distinction has philosophical roots. In a philosophical mode, you can spend a lifetime chasing necessary and sufficient conditions for a single concept. In a more Euclidean mode, you put forward assumptions you take to be warranted, investigate their consequences, and see if your inquiry yields fruitful results—new knowledge that encodes something about how the world is. The sciences, with their pragmatic bent, have clearly made progress by taking this approach.
The lesson for API documentation is direct: most reference docs are Euclidean by default, but the best documentation is Socratic. That’s the difference between a manual users merely read and one that lets them be productive right away.
If you can’t explain something clearly, there’s a decent chance you don’t truly understand it either. And if the API provider lacks that understanding, how can anyone else be expected to find it? Make the extra effort.
