Rendered at 03:36:27 GMT+0000 (Coordinated Universal Time) with Cloudflare Workers.
rkangel 5 hours ago [-]
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 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 7 hours ago [-]
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!
swyx 6 hours ago [-]
truly. its the kind of thing that makes docs people justify their jobs rather than coming from a founder or user centric pov
blanched 4 hours ago [-]
Maybe I'm incorrectly parsing your comment, but what does a "founder centric pov" for documentation look like?
NamlchakKhandro 2 hours ago [-]
looks like a load bearing seam with strong decisions
cwmoore 2 hours ago [-]
survivor biased models
jamilbk 5 hours ago [-]
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.
DanieleProcida 5 hours ago [-]
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.
nlawalker 4 hours ago [-]
Please post some kind of visible change notification (and something here) when you do!
LoganDark 4 hours ago [-]
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!
conradludgate 7 hours ago [-]
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.
WillAdams 4 hours ago [-]
I found it helpful in thinking about code and the approach for my current project:
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
i_v 2 hours ago [-]
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!
nchmy 5 hours ago [-]
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!
radicalriddler 6 hours ago [-]
Agreed, a couple months back, I got cf to crawl the site and created a block of skills around it for personal use.
c0rruptbytes 7 hours ago [-]
same, it’s great for first pass LLM docs
amazingman 3 hours ago [-]
You clearly do see the point!
keeganpoppen 2 hours ago [-]
[dead]
hahahaa 25 minutes ago [-]
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".
tedd4u 7 hours ago [-]
Posted many times. Here's the most recent time from 2024 (also has most discussion).
Same fundamental ideas, but I got a lot of things wrong in that earlier version (which is several years old now).
aeden 3 hours ago [-]
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.
wonger_ 5 hours 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.
wonger_ 2 hours ago [-]
Ah ok, thanks for clarifying contrived vs real. Like a videogame tutorial I suppose.
ashu1461 3 hours ago [-]
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.
lijok 5 hours ago [-]
Diataxis + ADRs + C4 = The holy trinity of docs
i_v 2 hours ago [-]
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.
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.
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.
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.
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.
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
Huge fan of Diataxis over the years!
https://news.ycombinator.com/item?id=42325011
Update: https://diataxis.fr/colophon/#origins-and-development (Divio came first).
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/
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.
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.
Really curious what the major differences are that have you preferring it over other methods / winging it.
[1]: https://c4model.com/