Socratic vs. Euclidean Forms of API Documentation

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:

And the way that Socratic mode of inquiry does is you try and define all your concepts, give the necessary and sufficient conditions for the thing that you're trying to study, right? So the Socratic approach to morality would be to say, okay, what is the necessary and sufficient conditions for an action to be good, right? The Socratic approach to epistemology — this has generated a ton of ink — is the question of what are the necessary and sufficient conditions to know something, right? These Socratic analyses of concepts. Most philosophy has gone this way, right?

And then there's this Euclidean mode, in which you don't try and do that. Rather what you do is you state some axioms that you take to be warranted, right? And this is where you get back to people like Wittgenstein and Reichenbach in terms of this idea that assumptions can be warranted even if they're not known or even if you don't have reasons to believe them necessarily, or sorry, you might have reasons to believe them, but they might not be empirically grounded reasons or things like that. But you put forward these assumptions, then you investigate the consequences of those assumptions. And given that the assumptions are meant to encode something about how you think the world is, you can get results out of that that constitutes new knowledge. You can have a fruitful inquiry, right?

And it's called Euclidean because the idea goes, Euclid has this whole geometry in which he has a set of axioms. And from there he's able to derive all these incredibly rich geometric concepts. But he never defines some of the primitive terms in these axioms. The example Glymour gives is the point, right? Euclid doesn't spend any time talking about what it is necessary and sufficient for, for something to be a point. He just uses this notion of a point in these axioms, and it's in investigating those axioms that you start to really get a sense of what a point is because you understand the role it plays in some system.

I think if you look at the history of Socratic projects, they're usually carried out in philosophy. Philosophy is a discipline where there's an active debate over whether it makes progress. I think philosophy does make progress in a lot of ways, but certainly the sciences which tend to take a more Euclidean approach, I think there could be no doubt the sciences have made progress. Although Kuhn would disagree with me there. But I certainly think there could be no doubt that the sciences have made progress. This does speak to this Euclidean way of doing things. I mean, you can just spend all your life trying to find out the necessary sufficient conditions of one thing, or you can just make an assumption and see if it leads to fruitful further consequences.

On Hacker News

Comments

[Antony]

If you can cite some examples of Socratic documentation, that would be great! I think React documentation is a decent example.

[HighScalability Team]

Well, I was going to point to some of my documentation for a state machine generator I made a while ago: https://github.com/ToddHoff/fgen, https://github.com/ToddHoff/fgen/blob/master/Internals.html, and https://github.com/ToddHoff/fgen/blob/master/Ssm/Ssm.pkg

Although rereading it I think doc is good, but it fails the Socratic test. It's hard!