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

61–66 of 66 posts

Re: Diátaxis

#61

Post by zenoprax »

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.

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).

Re: Diátaxis

#62

Post by zahrevsky »

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…

> 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?

Re: Diátaxis

#63

Post by mmargenot »

mmyrte wrote: post #49
mmargenot wrote: post #34

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…

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 o…

Sounds like good support for a few different paradigms.

Python has pretty good autogenerated reference docs, but if you want more than markdownified docstrings it makes them as difficult to maintain as the other pillars. As a set, the pillars aren’t as neatly grouped in Python documentation tooling, but I typically differentiate how-to, tutorial, etc with type tags in Notion or other indexes that point to where each type of thing lives.

Re: Diátaxis

#64

Post by rlpb »

vanderZwan wrote: post #40
rjmill wrote: post #37

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. Ple…

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.

A lookup table of normative specifications for every API call is Reference material. But a tour of API concepts is not (that would be Explanation). Nor is a Tutorial that introduces the API.

A lookup table of normative specifications of CLI arguments would also be Reference.

So they are not synonymous.

To be clear, I'm not advocating for navigation that must always have this structure in cases where it's redundant. I think people should do what makes sense. But I think it is nevertheless useful to not mix the different categories.

Re: Diátaxis

#65

Post by macartain »

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.

So its now 404'ing?

Re: Diátaxis

#66

Post by DanieleProcida »

zenoprax wrote: post #61
DanieleProcida wrote: post #13

Earlier quoted context omitted.

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).

At your request, https://diataxis.fr/atom.xml
Post reply on HN