3 ms·

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.

simplify 2y ago
What third dimension would you add?
- haydenchambers 2y ago
  [dead]
- euroderf 2y ago
  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.
  - DanieleProcida 2y ago
    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.
- taneliv 2y ago
  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.
riffic 2y ago
and I'll upvote it every time it comes up.
perlgeek 2y ago
A natural third dimension is language. If your user base is very international, you might need most of these documents in multiple languages.
- euroderf 2y ago
  User interface language is orthogonal to ebberyting.
remram 2y ago
For every dimension you add, you double the amount of docs you have to write.
- euroderf 2y ago
  You double the number of document types. But if it helps, it helps.

simplify 2y ago

What third dimension would you add?

haydenchambers 2y ago
[dead]
euroderf 2y ago
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.
- DanieleProcida 2y ago
  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.
taneliv 2y ago
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.

riffic 2y ago

and I'll upvote it every time it comes up.

perlgeek 2y ago

A natural third dimension is language. If your user base is very international, you might need most of these documents in multiple languages.

euroderf 2y ago
User interface language is orthogonal to ebberyting.

remram 2y ago

For every dimension you add, you double the amount of docs you have to write.

euroderf 2y ago
You double the number of document types. But if it helps, it helps.