(Found this old draft that was more or less complete; figured I should publish it.)
It's commonly appreciated that when explaining how to use something, there's a distinction between the high-level usage instructions and the low-level details. But what I've noticed is that different people draw the line a bit differently, and this leads to some confusion. A more useful, less ambiguous distinction, I find, is to break things into three levels, which I'm calling "implementation", "interface", and "workflow".
Implementation is what it sounds like -- how the thing works under the hood, ignoring all abstractions you might use to paper it over. You normally shouldn't have to worry about this unless something breaks, or you want to modify it, or maybe you just want to learn how it works so you can do something new, or whatever. It's what's below the abstraction.
Interface is what the thing does and not how it does it; this is necessarily an abstraction and won't always work, but it's at least what the thing is supposed to do in every case.
Workflow is how you normally use the thing -- not everything it does, just how it will respond when you do the things you normally do with it, not how it's going to respond in weird edge cases.
Note that these distinctions will only really work for artificial things -- something like, say, cooking, doesn't have a clean separation between implementation and interface, and even for something artificial this may not quite work if it's not sufficiently complete or well-implemented -- but this can still be a useful separation to draw even when that separation may not match the territory cleanly.
Now this may sound fairly obvious, but I bother pointing it out because apparently it's not so obvious! I can think of multiple conversations I've had where (in effect) I was given workflow information, found it insufficient, asked about the interface, and was asked, why do you need to know about such internals? Except, I wasn't asking about internals (implementation), I was asking about interface; I didn't want to know how the thing worked interally, just what it would do in cases outside the usual ones. So I think this three-level breakdown, even if it doesn't always map cleanly onto reality, still provides some useful terminology.
(Found this old draft that was more or less complete; figured I should publish it.)
It's commonly appreciated that when explaining how to use something, there's a distinction between the high-level usage instructions and the low-level details. But what I've noticed is that different people draw the line a bit differently, and this leads to some confusion. A more useful, less ambiguous distinction, I find, is to break things into three levels, which I'm calling "implementation", "interface", and "workflow".
Implementation is what it sounds like -- how the thing works under the hood, ignoring all abstractions you might use to paper it over. You normally shouldn't have to worry about this unless something breaks, or you want to modify it, or maybe you just want to learn how it works so you can do something new, or whatever. It's what's below the abstraction.
Interface is what the thing does and not how it does it; this is necessarily an abstraction and won't always work, but it's at least what the thing is supposed to do in every case.
Workflow is how you normally use the thing -- not everything it does, just how it will respond when you do the things you normally do with it, not how it's going to respond in weird edge cases.
Note that these distinctions will only really work for artificial things -- something like, say, cooking, doesn't have a clean separation between implementation and interface, and even for something artificial this may not quite work if it's not sufficiently complete or well-implemented -- but this can still be a useful separation to draw even when that separation may not match the territory cleanly.
Now this may sound fairly obvious, but I bother pointing it out because apparently it's not so obvious! I can think of multiple conversations I've had where (in effect) I was given workflow information, found it insufficient, asked about the interface, and was asked, why do you need to know about such internals? Except, I wasn't asking about internals (implementation), I was asking about interface; I didn't want to know how the thing worked interally, just what it would do in cases outside the usual ones. So I think this three-level breakdown, even if it doesn't always map cleanly onto reality, still provides some useful terminology.