Haven’t read through the full thing yet, but glad there’s a deeper dive into this model. Worried about the implication it has that these are the only four kinds of documentation. That closes out the space for discovering other kinds.
Also, I’m always irritated by how these all use “an encyclopedia entry on cooking” as an example of “reference”. C’mon people, there are way better choices! Flavor pairings, temperature charts, ratio books, substitutions, anything please.
I really like the implication that there are only four kinds of documentation. One of the issues I have with writing docs is setting up a framework so people can find the documentation they’re looking for, and a reasonably convincing argument for “these are the four elements of documentation” is enough that I can stop second-guessing myself and start filling in an outline. Also, when writing a single document, pinning it to one of the four categories helps me stay focussed: it’s tempting to go off on an explanatory tangent in a tutorial, or give a step-by-step example in a reference (especially if that information doesn’t exist elsewhere yet) but when I can tell myself “no, that’s material for the Tutorial section” I can stay fixed on the matter at hand.
Even if somebody does come up with a whole other kind of documentation someday, that doesn’t mean documentation organised this way will be bad, it just might be incomplete. And even if it’s incomplete, it’ll still be better organised and more accessible than documentation written without such a structure.
Haven’t read through the full thing yet, but glad there’s a deeper dive into this model. Worried about the implication it has that these are the only four kinds of documentation. That closes out the space for discovering other kinds.
Also, I’m always irritated by how these all use “an encyclopedia entry on cooking” as an example of “reference”. C’mon people, there are way better choices! Flavor pairings, temperature charts, ratio books, substitutions, anything please.
I really like the implication that there are only four kinds of documentation. One of the issues I have with writing docs is setting up a framework so people can find the documentation they’re looking for, and a reasonably convincing argument for “these are the four elements of documentation” is enough that I can stop second-guessing myself and start filling in an outline. Also, when writing a single document, pinning it to one of the four categories helps me stay focussed: it’s tempting to go off on an explanatory tangent in a tutorial, or give a step-by-step example in a reference (especially if that information doesn’t exist elsewhere yet) but when I can tell myself “no, that’s material for the Tutorial section” I can stay fixed on the matter at hand.
Even if somebody does come up with a whole other kind of documentation someday, that doesn’t mean documentation organised this way will be bad, it just might be incomplete. And even if it’s incomplete, it’ll still be better organised and more accessible than documentation written without such a structure.