Diátaxis: A Systematic Approach to Creating Better Technical Documentation
Diátaxis offers a structured framework for technical documentation by identifying four distinct user needs: tutorials, how-to guides, technical reference, and explanation. This approach helps creators organize content effectively, ensuring clarity for both users and maintainers without imposing rigid implementation constraints. By aligning documentation architecture with user goals, teams can build high-quality resources that are easier to discover and contribute to.
Diátaxis has allowed us to build a high-quality set of internal documentation that our users love, and our contributors love adding to.
- rkangel
I and my team did a full set of documentation for handing over a codebase to the client. A large complex codebase with accumulated history and subtle reasons why things were done.
Diataxis was fantastic. It took a bit of effort to work out what the page titles were to cover everything we needed, but then when you were writing a page it was glorious.
It was so clear what you were saying and what "voice" you were writing in. If it's a Reference page you're all descriptive, with diagrams and bullet points. When it's a guide you're more discursive, but you know you're just imparting information not trying to teach. It made it so much easier to be coherent and clear about everything.
- DanieleProcida
I'd like to take advantage of the attention it's getting to point out that I am working on translating Diátaxis into other languages https://diataxis.fr/translation/, and you can see an in-progress version with some partially completed translations at https://diataxis-translated.readthedocs.io/translation/.
- mmargenot
I love whenever this comes up. It’s a great framework for thinking about and writing docs.
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.
- Hnrobert42
I urge people to not read this. Once you do, you will see all documentation will as the flawed and confusing mess it is. Ignorance is bliss!
- CompoundEyes
I’ve been loving Diataxis! My agents follow guidance that links from other file types to a reference file type must be one way. Stays DRY. Also to regularly cut long reference files into smaller focused ones and link from the main.
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.md