Hacker News new | past | comments | ask | show | jobs | submit login

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/, 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.)




Guidelines | FAQ | Lists | API | Security | Legal | Apply to YC | Contact

Search: