I mean, there is nothing stopping people from using the [Diataxis Framework](https://diataxis.fr/) for any sort of documentation - it just doesn't have as great a foothold outside our sphere.
I was a bit surprised it or Divio (where it was created) announced when they talked about the four types of documentation. I would love to see it make its way into information systems curriculum, as it's a quite useful mental model.
I go back and forth on the usefulness of Diataxis and related information frameworks—Mark Baker (of EPPO fame) has an interesting series[1] about the DITA equivalent of task, concept, and reference:
> If there is a problem with DITA, then, it is not that it lacks a theory of information design. The problem is that many people actually believe that it does have a theory of information design, and that that theory can be summed up in three words: concept, task, and reference. But a theory for breaking content up into pieces is not a theory of information design unless it also includes a theory of how the pieces should go back together.
> There is, of course, nothing preventing DITA users from having or developing a sound theory about how the pieces should go back together. The problem is not that DITA does not provide one. The problem is that writers often do not see that they need one. They believe, or act as if they believed, that the devolution into concept, task, and reference is a complete information design. The result, generally, is Frankenbooks.
Which I think is a salient point, and less an indictment on the "three/four types" model than a reminder that you shouldn't just throw together a bunch of type-delineated docs for their on sake; the individual pieces have to make a functional whole.
So I'm certainly in favor of supplementing traditional OpenAPI-esque reference docs with more conceptual or task-based docs... provided that they're actually designed to complement each other.
ebiester|2 years ago
I was a bit surprised it or Divio (where it was created) announced when they talked about the four types of documentation. I would love to see it make its way into information systems curriculum, as it's a quite useful mental model.
spondylosaurus|2 years ago
> If there is a problem with DITA, then, it is not that it lacks a theory of information design. The problem is that many people actually believe that it does have a theory of information design, and that that theory can be summed up in three words: concept, task, and reference. But a theory for breaking content up into pieces is not a theory of information design unless it also includes a theory of how the pieces should go back together.
> There is, of course, nothing preventing DITA users from having or developing a sound theory about how the pieces should go back together. The problem is not that DITA does not provide one. The problem is that writers often do not see that they need one. They believe, or act as if they believed, that the devolution into concept, task, and reference is a complete information design. The result, generally, is Frankenbooks.
Which I think is a salient point, and less an indictment on the "three/four types" model than a reminder that you shouldn't just throw together a bunch of type-delineated docs for their on sake; the individual pieces have to make a functional whole.
So I'm certainly in favor of supplementing traditional OpenAPI-esque reference docs with more conceptual or task-based docs... provided that they're actually designed to complement each other.
[1] https://everypageispageone.com/2012/07/28/the-tyranny-of-the...