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.
We just invested a good amount of time restructuring our docs for Diátaxis. It was helpful, but I wouldn't take it as gospel. The important thing to remember is that each piece of content should be one of the four types.
If you're embarking upon a refactoring / rewriting journey for your docs, the only advice I'd share is to actually read the website beginning to end before starting. Especially this page: https://diataxis.fr/complex-hierarchies/. The guide is (unsurprisingly) very well written, and it's easy to internalize the concepts because they're repeated often.
Is there some way for me to be notified when you do? I don't see any RSS on your site.
The docs I have built up are at times too technical for users and not detailed enough for developers. I am not sure if it's a skill issue on my part for an individual piece of text, a skill issue on my part in applying the principles outlined by Diataxis, or a fault in the framework itself (or its self-documentation).
We're currently in the process of restructuring our documentation and I'd be very interested in an early draft of this, fully understanding that caveat emptor. Is it published anywhere currently?
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.
Ive been aware of diataxis for a while, but i hadnt considered such an approach. Will definitely keep it in mind for when im ready to generate some sort of docs. Thanks!
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.
I am sure that this exists for other ecosystems as well - rustdoc, Documenter.jl and Sphinx seem to support this - but my experience lies in R: three of the Diátaxis categories map quite nicely onto R package constructs:
- Tutorials are implemented as "vignettes", executed on package validation
- How-Tos are attached in roxygen documentation chunks, likewise executable by default - execution disabled when expensive or to avoid side effects.
- Reference is implemented in a TeX or Markdown format, commonly parsed by roxygen
The only thing that's missing is a canonical way of documenting implementation rationale. Having the documentation outside the repo worked before LLMs, but there was always that weak point of code drifting away from the documentation...
Something that Python gets right is that their entire docs site is versioned - select 2.7.18, for example, and you get the 2.7 docs right down to the tutorial. The Python development process is also very careful about keeping documentation up to date; the PEP process even requires an explicit "How to Teach This" section for proposals that add or change language features.
The concept of 4 different uses of documentation seems great. But I wonder why the presentation of Diaraxis itself is not clearly structured into these 4 different "views" on documentation? Or are they?
I love seeing this pop up again. Our customer support team has been steadily moving all of our docs over to Diátaxis for a while and it's been a really nice improvement.
I was not familiar with Diataxis, and as I was reading through the webpage, I kept wondering if there were any concrete examples. I love cooking, and it was interesting to see that some of the insights of the whole philosophy used teaching how to cook as an example.
I read a lot of cookbooks, and interestingly enough, I never stopped thinking about what makes a good cookbook (except for its recipes). Diataxis answers that in a way. Indeed, the best cookbooks I have read in some way or another followed Diataxis.
I can't help but notice that for a documentation organization framework/method it failed to produce its own good documentation.
There are repetitive bloated texts with unnecessary distractions and unenlightening illustrations. It is maybe well-organized, if one can speak about good organization of poorly expressed knowledge at all.
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.
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.
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. Please do not hide those from me while you "improve" your docs.
I'm genuinely confused about what one would expect under "reference" that isn't effectively API-shaped (in the context of software). Like, I've never consciously thought of this before but I can't remember a time that they haven't effectively been synonyms in my mind when I'm navigatig documentation.
That's part of the problem. Some projects, when they move to diataxis, will create a top level section called "reference" and have a single item under it called "API" (or similar.)
Depending on the docs theme, it can require clicking through to get to it.
It is a minor annoyance.
edit: Also gonna tack onto this that my original comment reads way more acerbic than I actually feel. I was sleepy and didn't proofread for tone like I normally do.
Oh like that. I was thinking of situations where "reference" just directly links to the API keyword index, e.g. the P5 docs[0], putting a redundant extra page between that would annoy me too.
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.
It seems like a typical french IT project: I have never heard about it, it looks very nice, but I can't quite figure out what kind of problem it solves.
1. In general, do whatever Wikipedia does. e.g., start with a one-sentence definition, then a couple paragraphs of summary, then go into short specified sections, and keep links to the "Citations" at the end. It's been refined for 25 years, it's older than most of your engineers, it's 50+% correct by default.
2. Keep every section to one screenful. If your reader can't see a headline, they get lost.
3. Put a funny picture at the top of the page. Or at least something off Wikimedia Commons.
4. Don't spend a lot of time writing anything. And don't use AI. The AI doesn't know what's inside your head. You yourself have an inkling. The longer you write, the further you'll get. Just write one short thing at a time and refactor aggressively later. Never throw shit over a fence blind. Nobody reads shit that's been flung over a fence.
Steven King said writing is telepathy. All mediated communication sits on a Pareto trade-off with face-to-face communication. Media is always less interactive with slower iterations. You need to figure out exactly what your audience needs, right when they're reading, and write just that, knock 'em dead, and leave. Don't add detail. They'll ask if they need detail.
> start with a one-sentence definition, then a couple paragraphs of summary, then go into short specified sections, and keep links to the "Citations" at the end. It's been refined for 25 years, it's older than most of your engineers, it's 50+% correct by default.
I went to a documentation workshop at Pycon UK by Daniele, and this was actually quite similar to his approach for writing front pages for documentation. He'd give the same questionnaire to a few teams, with prompts like "in one sentence, what is this product?", "What can a user accomplish with this product?", "Who are the primary users of this product?" Once everyone's aligned on answers, the page writes itself.
I don't have a problem with Diataxis itself but every time it comes up it saddens me because it is a reminder of how bad the technical writing community (by which, here I mean people who have technical writer as a job title) has been about popularizing and sharing their institutional knowledge, to the point that diataxis is far more popular and what a lot of people in tech think about when they think about technical writing.
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.
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/.
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!
truly. its the kind of thing that makes docs people justify their jobs rather than coming from a founder or user centric pov
Maybe I'm incorrectly parsing your comment, but what does a "founder centric pov" for documentation look like?
looks like a load bearing seam with strong decisions
survivor biased models
We just invested a good amount of time restructuring our docs for Diátaxis. It was helpful, but I wouldn't take it as gospel. The important thing to remember is that each piece of content should be one of the four types.
If you're embarking upon a refactoring / rewriting journey for your docs, the only advice I'd share is to actually read the website beginning to end before starting. Especially this page: https://diataxis.fr/complex-hierarchies/. The guide is (unsurprisingly) very well written, and it's easy to internalize the concepts because they're repeated often.
Ugh, I don't like that page and I have actually deleted it. It'll be gone soon.
There is a real problem there, and that page doesn't do a good enough job of dealing with it. I have something cooking that is much, much better.
Is there some way for me to be notified when you do? I don't see any RSS on your site.
The docs I have built up are at times too technical for users and not detailed enough for developers. I am not sure if it's a skill issue on my part for an individual piece of text, a skill issue on my part in applying the principles outlined by Diataxis, or a fault in the framework itself (or its self-documentation).
We're currently in the process of restructuring our documentation and I'd be very interested in an early draft of this, fully understanding that caveat emptor. Is it published anywhere currently?
Please post some kind of visible change notification (and something here) when you do!
It makes sense to me (I agree with it), but I also agree that it doesn't really deal with it. I look forward to whatever you're cooking!
Posted many times. Here's the most recent time from 2024 (also has most discussion).
https://news.ycombinator.com/item?id=42325011
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.
I found it helpful in thinking about code and the approach for my current project:
https://github.com/WillAdams/gcodepreview
In particular, it made it seem obvious to split up the documentation between:
- Overview --- readme.md
- Tutorials --- handled in various template files
- How to Guides --- embedded in the Literate Program code
- Reference --- the indices and Command Glossary
Ive been aware of diataxis for a while, but i hadnt considered such an approach. Will definitely keep it in mind for when im ready to generate some sort of docs. Thanks!
With tutorials, I’ve been enjoying handing my agent a directory of screenshots, talking out the process, then having it organize it all into a guide.
Huge fan of Diataxis over the years!
Agreed, a couple months back, I got cf to crawl the site and created a block of skills around it for personal use.
same, it’s great for first pass LLM docs
You clearly do see the point!
I used past tense for a reason ;)
Ah, fair! English can be so precise and yet still ... not quite :)
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.
I am sure that this exists for other ecosystems as well - rustdoc, Documenter.jl and Sphinx seem to support this - but my experience lies in R: three of the Diátaxis categories map quite nicely onto R package constructs:
- Tutorials are implemented as "vignettes", executed on package validation - How-Tos are attached in roxygen documentation chunks, likewise executable by default - execution disabled when expensive or to avoid side effects. - Reference is implemented in a TeX or Markdown format, commonly parsed by roxygen
The only thing that's missing is a canonical way of documenting implementation rationale. Having the documentation outside the repo worked before LLMs, but there was always that weak point of code drifting away from the documentation...
Something that Python gets right is that their entire docs site is versioned - select 2.7.18, for example, and you get the 2.7 docs right down to the tutorial. The Python development process is also very careful about keeping documentation up to date; the PEP process even requires an explicit "How to Teach This" section for proposals that add or change language features.
How is this different from Divio's documentation system?: https://docs.divio.com/documentation-system/
Update: https://diataxis.fr/colophon/#origins-and-development (Divio came first).
Same fundamental ideas, but I got a lot of things wrong in that earlier version (which is several years old now).
But when it comes to diagram, I still refer to the Divio version as Diataxis version description is too abstract.
Here you go, made a skill for it: https://github.com/peterknego/diataxis-docs-skill
Just released, alpha quality, need feedback/fine-tuning. Testing it now on my OSS repos.
I also admire what there isn't: certs, training, manifesto, "yah ain't holding it rite" blog posts, and job ads for a "Diátaxis Master".
Wait until it becomes popular.
Hypotaxis: arranging under
Parataxis: arranging alongside
Diátaxis: arranging across
The concept of 4 different uses of documentation seems great. But I wonder why the presentation of Diaraxis itself is not clearly structured into these 4 different "views" on documentation? Or are they?
Look at the left menu. There isn't a reference, because the concept really doesn't need a reference. All the others are there.
Perhaps add "A systematic approach to technical documentation authoring" to the title?
I love seeing this pop up again. Our customer support team has been steadily moving all of our docs over to Diátaxis for a while and it's been a really nice improvement.
I was not familiar with Diataxis, and as I was reading through the webpage, I kept wondering if there were any concrete examples. I love cooking, and it was interesting to see that some of the insights of the whole philosophy used teaching how to cook as an example.
I read a lot of cookbooks, and interestingly enough, I never stopped thinking about what makes a good cookbook (except for its recipes). Diataxis answers that in a way. Indeed, the best cookbooks I have read in some way or another followed Diataxis.
Much of the Canonical & Ubuntu documentation uses it now. I am not sure which are the best examples though.
https://ubuntu.com/server/docs/
I can't help but notice that for a documentation organization framework/method it failed to produce its own good documentation.
There are repetitive bloated texts with unnecessary distractions and unenlightening illustrations. It is maybe well-organized, if one can speak about good organization of poorly expressed knowledge at all.
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.
[0] https://passo.uno/seven-action-model/
> ...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.
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. Please do not hide those from me while you "improve" your docs.
I'm genuinely confused about what one would expect under "reference" that isn't effectively API-shaped (in the context of software). Like, I've never consciously thought of this before but I can't remember a time that they haven't effectively been synonyms in my mind when I'm navigatig documentation.
That's part of the problem. Some projects, when they move to diataxis, will create a top level section called "reference" and have a single item under it called "API" (or similar.)
Depending on the docs theme, it can require clicking through to get to it.
It is a minor annoyance.
edit: Also gonna tack onto this that my original comment reads way more acerbic than I actually feel. I was sleepy and didn't proofread for tone like I normally do.
Oh like that. I was thinking of situations where "reference" just directly links to the API keyword index, e.g. the P5 docs[0], putting a redundant extra page between that would annoy me too.
[0] https://processing.org/reference
Diataxis + ADRs + C4 = The holy trinity of docs
I had to search these terms, does ADR mean ‘Architecture decision record’ and C4 the ‘C4 model’? How do you combine them in documentation?
C4[1]? Hadn’t heard of it until now. Thanks!
Really curious what the major differences are that have you preferring it over other methods / winging it.
[1]: https://c4model.com/
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.
It seems like a typical french IT project: I have never heard about it, it looks very nice, but I can't quite figure out what kind of problem it solves.
I've also found these guidelines helpful:
1. In general, do whatever Wikipedia does. e.g., start with a one-sentence definition, then a couple paragraphs of summary, then go into short specified sections, and keep links to the "Citations" at the end. It's been refined for 25 years, it's older than most of your engineers, it's 50+% correct by default.
2. Keep every section to one screenful. If your reader can't see a headline, they get lost.
3. Put a funny picture at the top of the page. Or at least something off Wikimedia Commons.
4. Don't spend a lot of time writing anything. And don't use AI. The AI doesn't know what's inside your head. You yourself have an inkling. The longer you write, the further you'll get. Just write one short thing at a time and refactor aggressively later. Never throw shit over a fence blind. Nobody reads shit that's been flung over a fence.
Steven King said writing is telepathy. All mediated communication sits on a Pareto trade-off with face-to-face communication. Media is always less interactive with slower iterations. You need to figure out exactly what your audience needs, right when they're reading, and write just that, knock 'em dead, and leave. Don't add detail. They'll ask if they need detail.
> start with a one-sentence definition, then a couple paragraphs of summary, then go into short specified sections, and keep links to the "Citations" at the end. It's been refined for 25 years, it's older than most of your engineers, it's 50+% correct by default.
I went to a documentation workshop at Pycon UK by Daniele, and this was actually quite similar to his approach for writing front pages for documentation. He'd give the same questionnaire to a few teams, with prompts like "in one sentence, what is this product?", "What can a user accomplish with this product?", "Who are the primary users of this product?" Once everyone's aligned on answers, the page writes itself.
I don't have a problem with Diataxis itself but every time it comes up it saddens me because it is a reminder of how bad the technical writing community (by which, here I mean people who have technical writer as a job title) has been about popularizing and sharing their institutional knowledge, to the point that diataxis is far more popular and what a lot of people in tech think about when they think about technical writing.
The old (now legacy) apple documentation roughly seemed to follow this pattern I think.