3 ms·

> API doc tends to be Euclidean, but at its best documentation is Socratic. That’s when you can really be productive—fast. Socratic documentation is necessary,

> API doc tends to be Euclidean, but at its best documentation is Socratic. That’s when you can really be productive—fast. Socratic documentation is necessary, but you need both. You really do need both. When I come back to your library after a year of not using it, and I can't remember the name of a slightly obscure function, I don't want to have to dig around in prose for the sentence where you explain what it does. I want to be able to search for a few keywords and get a function definition, with the arguments and the return type listed, and a short description of what it does. (If possible, I want to be able to search by the type; the only language that I've ever seen have this feature is Haskell, even though it would be doable in any statically typed language.)

patrickmay 7y ago
You seem to be describing the difference between a User Guide and a Reference Manual. Both are needed.
- crispyambulance 7y ago
  You're right that both of these forms are needed. There is, however, yet another category of documentation that is increasingly common and often becoming necessary in order to cope. I don't know if it has a formal name, but let's call it "context-sensitive" documentation. Some examples that come to mind are when you have auto-completion, "light=bulbs" or intellisense in IDE's, or -? options in the commandline. In situations where you are just trying to get stuff done, and you forget something trivial-- it's usually not some extremely complex edge-case, it's usually something mundane that you forgot because you don't often do that particular task everyday. In such scenarios, it's infuriating to have to skim through detailed man pages that cover every damn exotic use-case of the the command in alphabetical order, nor is it pleasant to pick up a user guide that starts from the most fundamental basics. There's room for documentation that sort-of reads you rather than the other way around. This kind of stuff has sometimes gotten a bad rap, since the days of "clippy" but it's getting better. In the IDE world, there was Resharper, and now even the Rosyln for dotnet has this stuff increasingly built in.
warrenm 7y ago
Any reason you clipped that quote short? >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.

patrickmay 7y ago

You seem to be describing the difference between a User Guide and a Reference Manual. Both are needed.

crispyambulance 7y ago
You're right that both of these forms are needed. There is, however, yet another category of documentation that is increasingly common and often becoming necessary in order to cope. I don't know if it has a formal name, but let's call it "context-sensitive" documentation. Some examples that come to mind are when you have auto-completion, "light=bulbs" or intellisense in IDE's, or -? options in the commandline. In situations where you are just trying to get stuff done, and you forget something trivial-- it's usually not some extremely complex edge-case, it's usually something mundane that you forgot because you don't often do that particular task everyday. In such scenarios, it's infuriating to have to skim through detailed man pages that cover every damn exotic use-case of the the command in alphabetical order, nor is it pleasant to pick up a user guide that starts from the most fundamental basics. There's room for documentation that sort-of reads you rather than the other way around. This kind of stuff has sometimes gotten a bad rap, since the days of "clippy" but it's getting better. In the IDE world, there was Resharper, and now even the Rosyln for dotnet has this stuff increasingly built in.

warrenm 7y ago

Any reason you clipped that quote short? >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.