31–40 of 66 posts
I never saw the point in Diataxis, but honestly while vibe coding it's pretty convenient to tell an LLM "do diataxis" and get decent first pass documentation out of it.
Another documentation model: Fabrizio's seven actions [0]. People read docs to appraise, understand, explore, practice, remember, develop, and troubleshoot, usually in that order. It feels so natural and obvious compared to Diataxis' forced abstractions, where I'm still left wondering "what's the difference between a tutorial and a how-to guide?" But! I'm glad for anything that helps people organize and maintain docs…
> ...where I'm still left wondering "what's the difference between a tutorial and a how-to guide?" I don't find this question difficult. Without looking anything up, a tutorial exercises a contrived example for learning purposes, whereas a how-to guide provides instructions suitable for real world execution.
It’s hard to keep documentation up to date, however, and I find that items like tutorials and reference materials (unless generated off versioned code) can drift pretty far over time.
A feature I like in concept that notion introduced with wikis ages ago was a “verification” timestamp, where you specify a timeframe after which the doc owner has to reconfirm that the doc is up to date. A bit too easy to rubber stamp, unfortunately, but maybe if it took the doc offline entirely without a more robust audit.
tutorial/setup-buh-snuh-env.md
how-to/configure-buh.md
install-snuh.md
reference/buh.md
snuh.md
snuh-licenses.md
explanation/why-we-use-buh.mdOverall, the movement is good, except for how it tends to turn 1-click docs into 2-click docs (or more for folks who don't know that API docs probably live under reference.)
You are allowed to have a top level tab/link to API docs. Please do not hide those from me while you "improve" your docs.
Please do not make me click on "reference" to get to "API docs". I love diataxis, but dear lord, do not make me click an extra time to get to the thing I actually need 95% of the time. Overall, the movement is good, except for how it tends to turn 1-click docs into 2-click docs (or more for folks who don't know that API docs probably live under reference.) You are allowed to have a top level tab/link to API docs. Ple…