3 ms·

https://diataxis.fr https://diataxis.fr (or the original of that page) was posted on HN recently, and I thought it was fairly interesting; I haven't had an oppo

by maicro 5y ago

https://diataxis.fr https://diataxis.fr (or the original of that page) was posted on HN recently, and I thought it was fairly interesting; I haven't had an opportunity to apply it to my own technical writing yet (I wear many hats, and "documentation writer" hasn't been needed recently), but I'm keeping it handy for when I do.

kaycebasques 5y ago
The ideas behind Diataxis née [1] Divio's Documentation System are one of the cardinal rules of technical writing. Most if not all professional technical writers divide their documentation into content types along those lines. By the way they didn't come up with that idea; they just have the most accessible explanation of it :D Are you just mentioning it in passing (because I mentioned technical writing) or is there a connection to erotetics that I'm not seeing? Another very useful practice is to take an inventory of all existing documentation (in a spreadsheet for example) and mark which ones fall neatly into one of the doc types (tutorial/guide/explanation/reference) and which ones are a mix. The mixed ones are candidates for refactor. This practice also helps quickly uncover content gaps (e.g. "ah, we have a guide and explanation on the login workflow but no reference for the login APIs!"). [1] https://www.merriam-webster.com/dictionary/n%C3%A9e https://www.merriam-webster.com/dictionary/n%C3%A9e (my fancy word for the day :D)
- maicro 5y ago
  Pretty much mentioning it in passing - it's hard to tell the experience level of random commenters online, so thought I might pass that along in case you were unfamiliar; I've done _some_ technical writing for work, but not enough, and none formal enough, to be familiar with the cardinal rules, so Diataxis has been in the back of my head for the last week+ since I saw it posted on HN. Thank you for the seemingly positive review of them though X) And hey, if you have any other good resources (even if less accessible), I'm always looking to learn. And yes, nee (or née if I just steal your accented version) is a useful word X)

by maicro 5y ago

kaycebasques 5y ago

The ideas behind Diataxis née [1] Divio's Documentation System are one of the cardinal rules of technical writing. Most if not all professional technical writers divide their documentation into content types along those lines. By the way they didn't come up with that idea; they just have the most accessible explanation of it :D Are you just mentioning it in passing (because I mentioned technical writing) or is there a connection to erotetics that I'm not seeing? Another very useful practice is to take an inventory of all existing documentation (in a spreadsheet for example) and mark which ones fall neatly into one of the doc types (tutorial/guide/explanation/reference) and which ones are a mix. The mixed ones are candidates for refactor. This practice also helps quickly uncover content gaps (e.g. "ah, we have a guide and explanation on the login workflow but no reference for the login APIs!"). [1] https://www.merriam-webster.com/dictionary/n%C3%A9e https://www.merriam-webster.com/dictionary/n%C3%A9e (my fancy word for the day :D)

maicro 5y ago
Pretty much mentioning it in passing - it's hard to tell the experience level of random commenters online, so thought I might pass that along in case you were unfamiliar; I've done _some_ technical writing for work, but not enough, and none formal enough, to be familiar with the cardinal rules, so Diataxis has been in the back of my head for the last week+ since I saw it posted on HN. Thank you for the seemingly positive review of them though X) And hey, if you have any other good resources (even if less accessible), I'm always looking to learn. And yes, nee (or née if I just steal your accented version) is a useful word X)