Hacker Newsnew | past | comments | ask | show | jobs | submitlogin

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.


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


User interface language is orthogonal to ebberyting.


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


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


You double the number of document types. But if it helps, it helps.


What third dimension would you add?


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.


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.


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.




Guidelines | FAQ | Lists | API | Security | Legal | Apply to YC | Contact

Search: