Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Diátaxis

diataxis.fr

Post reply on HN
Print view View original

21–30 of 66 posts

Re: Diátaxis

#21

Post by nlawalker »

DanieleProcida wrote: post #13
jamilbk wrote: post #12

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://dia…

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.

Please post some kind of visible change notification (and something here) when you do!

Re: Diátaxis

#22

Post by WillAdams »

conradludgate wrote: post #3

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

Re: Diátaxis

#23

Post by blanched »

swyx wrote: post #7
Hnrobert42 wrote: post #4

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?

Re: Diátaxis

#24

Post by ashu1461 »

wonger_ wrote: post #18

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…

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.

Re: Diátaxis

#25

Post by aeden »

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.

Re: Diátaxis

#27

Post by i_v »

lijok wrote: post #9

Diataxis + ADRs + C4 = The holy trinity of docs

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/

Re: Diátaxis

#28

Post by i_v »

conradludgate wrote: post #3

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.

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!

Re: Diátaxis

#29

Post by NamlchakKhandro »

blanched wrote: post #23
swyx wrote: post #7

Earlier quoted context omitted.

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
Post reply on HN