Comment by wonger_
1 day ago
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.
Ah ok, thanks for clarifying contrived vs real. Like a videogame tutorial I suppose.
How to guide is for things which you want to do, probably not without going in depth or understanding the technicalities.
Example in our codebase
- How to clear the cache ?
- How to configure the logger ?
I liked the idea of separating our how to guides and explanations / tutorials, because sometimes you just want engineers to follow a specific flow without going too much in depth.