« 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 documentat

« 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. » I agree that the last sentence describes the most common form of reference documentation. But I think characterising it as "state your axioms and let users derive the rest" is too generous. Typically what you have to do isn't so much "derive" as "make educated guesses". As far as I'm concerned, the problem is that most of this documentation _isn't_ stating its axioms. It's much more common for each function to have a description in terms of definitions and concepts which aren't further defined. And very often if a piece of behaviour doesn't have any knobs controlling it, it doesn't get documented at all. I dislike the dichotomy presented here, where this form of bad documentation is on one side, and "A FAQ, recipes for common tasks, and working code examples" are on the other. Those are all fine things to have, but they're not really a substitute for setting out directly, in the reference documentation, just what it is the software is promising to do.