evildmp
Use the diataxis framework for the diataxis framework website?
I was highly surprised when I realized that the website describing the framework does NOT follow what it describes. When looking for tutorials or references it isn't always clear where to look without reading everything.
I saw a related post about this very subject but that didn't get any followup discussion/comments. I believe it's an issue though, so I'm opening this instead.
The current side menu isn't clear what each section is, there is a mix of reference & explanation...
Copying what @wolftune said in that post, the website could/should be re-structured with something like:
- Tutorial: A guide through the experience of making all 4 types of documentation using some clear example case, even if silly
- How-to: Practical steps for separating things into the 4 types, for the step-by-step questions and answers to consider to flesh out each type, etc.
- Reference: There's some of this already, the summary tables and such, it's just mixed with explanation and incomplete
- Explanation: the whole Diataxis website seems primarily explanation right now
We may need another toplevel category for other pages.
Would you accept contributions to change the website structure? Have you thought about this already? Were there roadblocks that made you do the current structure instead?
