I'm a little less than impressed by the presentation here. The idea that Divio is describing here is the Diataxis framework (https://diataxis.fr/), which "is the work of" (https://diataxis.fr/colophon/) Daniele Procida (https://vurt.eu/). Who, incidentally, is also giving the PyCon talk in the video on the page you linked (https://www.youtube.com/watch?v=t4vKPhjcMZg). But I don't see anything resembling attribution for the ideas. They aren't just common industry knowledge or "received wisdom". (And the "quote" from David Laing at the top isn't really accomplishing anything, either.)
I’m not that impressed with Diataxis, considering it is basically describing the approach of Django project’s docs—which (both docs and the aporoach) predate Diataxis by many years—without giving any credit that I know of.
Jacob Kaplan-Moss described[0] the approach in 2009 (he omitted the How To guides, but they are in fact part of Django docs for as long as the framework is widely used). If there was a person to credit for this, that would be him.
I don't think this is quite the same idea, and it isn't anywhere near as deeply elaborated, nor given a theoretical basis. Of course no concept on this scale just pops out of the ether fully formed - as I noted elsewhere, the dichotomy (tetrachotomy?) described by the Diataxis model bears a striking similarity to that in Kalb's model of experimental learning. But that's just it - Diataxis could claim that much more strongly as an ancestor than Kaplan-Moss' approach, which is simply proposing that multiple forms of documentation exist and should co-exist to complement each other, without proposing why or how.
Although this actually gets at a frustration I had with Johnson's essay. There's a section that presents research and examines the VSK model and Kalb's model, and in both cases finds: a) they're wrong, in the sense that they hypothesize different kinds of learners that don't exist; and b) they're useful, in the sense that they describe different kinds of stimuli that should exist in a learning environment. Not because they serve the needs of different students, but because they serve the needs to students at different times or in different conditions.
But instead of applying those lessons, Johnson basically uses the findings about VSK to dismiss critics, and spends dozens of pages re-deriving an approximation of Diataxis theory which would have flowed directly from mapping the Kalb model onto forms of technical writing (which, while not quite the same thing as "documentation", is good enough to get to the right conclusions).
It would omit what Johnson calls "lesson plans", but these seem to be basically just the source code for tutorials. And it would omit "textbooks", but I think a lot of these are bad anyway, for many of the same reasons that board game rulebooks are.
Thanks. I already had "something about Diataxis" somewhere on my blog agenda before the HN post, and between this and the rest of the comments and the article I feel like I have a lot more material now.
