News for hackers. Stuff that matters.
Re:Diátaxis – A systematic approach to technical documentati... by euroderf on Thursday December 05, 2024 @01:12AM (#42325438)
A frequent post to HN. It seems there is appeal in trying to systematize the entire idea of TC. I'd like to see this extended to three dimensions.
Re:Diátaxis – A systematic approach to technical documentati... by simplify on Thursday December 05, 2024 @01:25AM (#42325516)
What third dimension would you add?
Re:Diátaxis – A systematic approach to technical documentati... by euroderf on Thursday December 05, 2024 @03:59AM (#42326317)
Fair question. I've read a couple of critiques of Diátaxis that suggest additional boxes.

FAQs and "Gotchas" need a "home box". So do gists. Maybe a third dimension would be something like "degree of curation" or "need for taxonomy and organisation" ?

FWIW... DITA has concepts, tasks, & references - and AFAICT these map fairly nicely to Diátaxis.

Re:Diátaxis – A systematic approach to technical documentati... by DanieleProcida on Thursday December 05, 2024 @04:10AM (#42326384)
FAQ lists are the equivalent of the box in my garage where I put things when I've been told to get them out of the house, and I can't actually be bothered to put them in the right place.
Re:Diátaxis – A systematic approach to technical documentati... by taneliv on Thursday December 05, 2024 @10:57AM (#42329371)
Depth?

Like, three line basic how-to vs. one that shows how to (!) achieve something more complex, or not intuitively possible to perform with the tool being documented. Explanations that only tell you why you would not want to use the tool, sort of a laundry list of things that you can't or shouldn't be doing with it, and should be using something else, as opposed to a comprehensive look into how (or why) the tool works, and how it is better than competition, for example.

Not sure if that makes sense from a more systematic point of view, but it could easily help structure your documentation: "The Tutorial" and below it "list of additonal advanced and obscure mini-tutorials".

This is not to say anything about the length of each document, but naturally shallower ones could often be shorter.

Re:Diátaxis – A systematic approach to technical documentati... by riffic on Thursday December 05, 2024 @01:26AM (#42325524)
and I'll upvote it every time it comes up.
Re:Diátaxis – A systematic approach to technical documentati... by perlgeek on Thursday December 05, 2024 @07:24AM (#42327513)
A natural third dimension is language. If your user base is very international, you might need most of these documents in multiple languages.
Re:Diátaxis – A systematic approach to technical documentati... by euroderf on Thursday December 05, 2024 @07:47AM (#42327698)
User interface language is orthogonal to ebberyting.
Re:Diátaxis – A systematic approach to technical documentati... by remram on Thursday December 05, 2024 @10:42AM (#42329224)
For every dimension you add, you double the amount of docs you have to write.
Re:Diátaxis – A systematic approach to technical documentati... by euroderf on Thursday December 05, 2024 @02:10PM (#42331456)
You double the number of document types. But if it helps, it helps.