1. 11

  2. 5

    This is a very interesting idea. Unfortunately, the essay itself is Euclidean instead of Socratic.

    It would be very helpful to have some short exceprts that demonstrate the Socratic approach, and show how it helps the user understand some internal detail of a system. And maybe some examples of the sort of easy mistakes that you should look out for when writing in a Socratic style. And, of course, examples of Socratic documentation, even mediocre examples, from real-world APIs. Oh, and obviously a FAQ would be nice.

    Oh well, at least the absence of these things helps make it clear why they are good things to have!

    1. 3

      I like the narrative documentation idea, which seems similar to the “Socratic” documentation the author describes, but is presented in narrative style and is therefore its own justification.

      1. 3

        I’m in the middle of listening to the Socratic dialog on Audible. I’ll be honest, from where I stand, Socrate documenting an API would be him claiming that he does not know what a good API is, then asking me to try to explain to him what make a good API, then after I said something, he would hijack the conversation for 20 minutes where he would rave about the good and why since a physician is good by the virtue of curing the disease, the API is good by virtue of curing the database of its inconsistencies (or whatever), then use that long harangue to display to me that I don’t know what a good API is, then I would ask him a bit frustrated “well, what make an API good”, to which he would answer that he does not know because he does not know what the “good” is and that he need me to teach him. Go back to beginning and start over, until I get frustrated and start thinking that this guys would sure deserve to be put to death for being so damn annoying.

        Of course he would barely mention the API itself, but then, since we don’t know what the good is, we can’t know what a good API is, and because of this, we cannot know if that particular API is of any good. “And yet, you seems to know what a great API is, but you refuse to tell me!” would probably have been uttered at some point in the dialog.

        Yeah, the Socratic dialog are great to listen to. 😆

        1. 2

          Yes, the term “Socratic dialog” has come a long way from what Socrates himself actually engaged in. But then, it has been a couple thousand years, so maybe that’s not surprising.

        2. 1

          Some of the early AWS product releases might have fit the Socratic label, had we thought to use it. They almost always featured an FAQ as the main documentation link. The (usually less than 10) questions tended to introduce the intended use case and build towards an example implementation. They also were clever in sneakily steering you away from parts of the API that were tricky or incomplete, but it was marketing copy, I suppose. Overall it wasn’t a bad format for an intro doc, but I suspect they let the actual API spec get released at a lower quality in hopes nobody would read that far.