Join the discussion
Write your take first — we'll ask for email only when you're ready to publish.
- Hacker News
- 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.
by 5ersi - 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.by voidhorse
- 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".by hahahaa
- Wait until it becomes popular.by d0mine
- 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).
- But when it comes to diagram, I still refer to the Divio version as Diataxis version description is too abstract.by yipinwong
- Same fundamental ideas, but I got a lot of things wrong in that earlier version (which is several years old now).
- 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.
by cryptopian - 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.
by mmargenot - 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.by nneonneo
- 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...
by mmyrte - 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.
- yeah, the urge to turn this page into a skill and then just let it run loose on all my random vibe-coded side projects is very, very strong. seems great for that kind of thing.by keeganpoppen
- You clearly do see the point!by amazingman
- same, it’s great for first pass LLM docsby c0rruptbytes
- Agreed, a couple months back, I got cf to crawl the site and created a block of skills around it for personal use.
- 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!
by i_v - 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!by nchmy
- 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
by WillAdams - Posted many times. Here's the most recent time from 2024 (also has most discussion).by tedd4u
- 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.
by jamilbk - > read the website beginning to end before starting
Huh. The “Start here” page says exactly the opposite. It's literally the first two sentences on the page:
> You don’t need to read everything on this website to make sense of Diátaxis, or to start using it in practice. In fact I recommend that you don’t.
So what makes you recommend reading it all first?
by zahrevsky - 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.
- 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!by Hnrobert42
- truly. its the kind of thing that makes docs people justify their jobs rather than coming from a founder or user centric povby swyx
- 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 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.
by rkangel