I was emailing a service about their documentation and while their doc was good, about one particularly tricky concept they told me that once you use it for a while, that’s when you’ll understand it.
In other words: you’ll only understand it after you understand it.
I didn’t like that response. I want documentation that takes me from an unproductive newbie to a somewhat functioning journeyperson. Not an expert, but I want to get stuff done as soon as possible. And for that you need to understand the mental model behind the API. Otherwise, how do you know how to make anything happen?
I realize it’s hard to make good documentation. I spent a lot of time writing Explain the Cloud Like I'm 10 just to communicate the mental model behind the cloud. It’s not easy.
Then I read that something that showed me there are two different styles of documentation: Euclidean and Socratic:
Euclidean - state your axioms and let users derive the rest. Easiest for the API provider, but hardest on the user. This is the most common form of documentation. You see it all the time. Each entry point in the API is sort of explained, but there’s nothing tying the whole API together. You just pray someone on Stackoverflow already asked the questions you want to ask and someone made the effort to answer—before the question was voted into oblivion.
Socratic - an open-inquiry meant to bring about a deeper understanding in the API user. You get the Euclidean part, but you also get a FAQ, you get recipes for common tasks, you get error conditions and possible responses, and you get working code examples. You get a deep explanation of what the API is trying to accomplish and how you can use it to accomplish your own goals. People tend to think once they've written an example on GitHub that they've fulfilled their Socratic duty. Not so. You need to help people get to the point where they could write the example code. The person who works at the company and wrote the example already knows all that, but it's that knowledge that must be communicated, not the end product.
API doc tends to be Euclidean, but at its best documentation is Socratic. That’s when you can really be productive—fast.
If you can't explain something well, it's likely you don't understand it either. And if you don't understand it as an API provider, how is anyone else going to understand it? Please make that extra effort.
What did I read that explained the idea of Euclidean vs Socratic approaches to a topic? Take a look at this interview with David B. Kinney on the Philosophy of Science: