3 ms·

> In proportion as a man is thinking scientifically when he makes a statement, he knows the statement is the answer to a question and he knows what the question

> In proportion as a man is thinking scientifically when he makes a statement, he knows the statement is the answer to a question and he knows what the question is. Interesting way of looking at communication! I might be able to apply this to technical writing (my line of work). Sometimes you write some content and it feels out of place or awkward. Perhaps asking "what question is this statement an answer to?" might clarify what to do with the content. I also find it effective to sometimes literally start each paragraph with the question that the paragraph is answering. It helps keep the writing focused.

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)

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)