3 ms·

> The main instances where the 4doc model is glaringly incomplete for me are homepages and release notes. I think the main benefit of 4-doc model is that it ma

by js8 3y ago

> The main instances where the 4doc model is glaringly incomplete for me are homepages and release notes. I think the main benefit of 4-doc model is that it makes you think about use cases for documentation. I think what you're alluding to is that there are more use cases. The "release notes" serve the "I want to get overview of what changed" use case. The "homepage" serves the "I want to get a quick overview of the thing and see if I can use it" use case. It's not clear though how the model could be extended to accomodate the above.

DanieleProcida 3y ago
Daniele here. Tutorials, how-to guides, reference, explanation are modes of documentation. They are not an exhaustive list of every kind of content that should appear in your documentation. Diátaxis is not a list of four boxes into which all content should be mercilessly shoved whether it fits or not. Consider: a homepage, an introduction, a foreword, a contents page, a landing page for a section, an index, credits, a list of contributors (I am sure you can think of more). These can all be important. Documentation without a homepage would be positively stupid. I don't think we should have sections that are not introduced by landing pages. Diátaxis doesn't prescribe anything for them, not because they are not important, but because they are not themselves modes of documentation. They are part of its furniture, if you like - just as an introduction, translator's note etc might be an important part of a book, but nothing whatsoever to do with the story it contains. Homepages and landing pages are explicitly mentioned at https://diataxis.fr/complex-hierarchies/ https://diataxis.fr/complex-hierarchies/, by the way. (Release notes could equally well be expressed as reference or in a section on their own. It really doesn't matter. It doesn't seem like something Diátaxis needs to worry about.)
kaycebasques 3y ago
Yes, exactly. I called them goals in my original post. You call them use cases. Diataxis refers to them as modes. I think it's worthwhile to explore whether there are more modes out there, and whether the existing 4 modes is the most useful framing. And the natural way to do this is to look at docs in the wild and think about how they line up with the existing modes.

by js8 3y ago

DanieleProcida 3y ago

Daniele here. Tutorials, how-to guides, reference, explanation are modes of documentation. They are not an exhaustive list of every kind of content that should appear in your documentation. Diátaxis is not a list of four boxes into which all content should be mercilessly shoved whether it fits or not. Consider: a homepage, an introduction, a foreword, a contents page, a landing page for a section, an index, credits, a list of contributors (I am sure you can think of more). These can all be important. Documentation without a homepage would be positively stupid. I don't think we should have sections that are not introduced by landing pages. Diátaxis doesn't prescribe anything for them, not because they are not important, but because they are not themselves modes of documentation. They are part of its furniture, if you like - just as an introduction, translator's note etc might be an important part of a book, but nothing whatsoever to do with the story it contains. Homepages and landing pages are explicitly mentioned at https://diataxis.fr/complex-hierarchies/ https://diataxis.fr/complex-hierarchies/, by the way. (Release notes could equally well be expressed as reference or in a section on their own. It really doesn't matter. It doesn't seem like something Diátaxis needs to worry about.)

kaycebasques 3y ago

Yes, exactly. I called them goals in my original post. You call them use cases. Diataxis refers to them as modes. I think it's worthwhile to explore whether there are more modes out there, and whether the existing 4 modes is the most useful framing. And the natural way to do this is to look at docs in the wild and think about how they line up with the existing modes.