5 ms·

The article discusses the structure of documentation as three pillars: the what, the why, and the how. I prefer to think about documentation in terms of four

The article discusses the structure of documentation as three pillars: the what, the why, and the how. I prefer to think about documentation in terms of four audiences: - the student (tutorials) - the chef (how-to guides) - the theorist (explanations) - the technician (API references) Divio [1] has an excellent set of articles that explains this approach to documentation. [1] https://documentation.divio.com/ https://documentation.divio.com/

rsolva 4y ago
The same excellent documentation framework is also available on this company-independent website: diataxis.fr
- alipitch 4y ago
  Thanks! Also checked the github site. https://github.com/evildmp/diataxis-documentation-framework https://github.com/evildmp/diataxis-documentation-framework
- catchclose8919 4y ago
  ...this is questionable advice that goes against the interest of programmers having stuff to do - we're not segmented into audiences. We want multi-level docs combined/spliced/interwoven together so we can get our work done without wasting gandalfing the docs. > While redesigning the Cloudflare developer docs ...oh, so this is the reason for CF's docs totally uncomprehensible and confusing mess. They've made getting to anythin so comfusing that AWS seems a breath of fresh air in comparison. I dunno, maybe other peoples' brains are wired totally different than mine, but boy, these new fever of "writing better docs" seems to produce the exact opposite effects whenever applied. The few enojoyable docs nowadays seem to be written by old-school unixy geeks and/or people that are not programmers or worse, "documentation developers": physicists, mathematicians, biologists, quants, data analysts etc. seem to do a nice job when they have the time.
drothlis 4y ago
Just watched Daniele's talk. Brilliant, practical advice. Thanks so so much for the link.
catchclose8919 4y ago
> - the theorist (explanations) Further it's explained that this is where the "understanding" bit comes in. Ugh, so this school of thought is where some of the terrible modern documentation comes from... I want the explanations/understanding first COMBINED with a minimal how-to guide serving as illustration for the explanation. Then a quick link to an API reference that INCLUDES snippets of explanations and usage examples (that you'd find in tutorials or how-to guides). Separating thinking about documentation this way leads to horrible documentation where you start with dumbed-down tutorials missing lots of crucial information, and then you have to put in tons of unnecessary effort putting disparate things toget ther in your head. FFS, programmers are rarely students since most of what we learn is learning-on-the-job and never chefs or theoreticians. Tutorials always waste your time so you'd prefer to start with something much denser... only that the only thing denser you easily find are the API docs, and you lack the explanations to understand them and usage exmaples so you have to hunt them for yourself... yuck. As an example of GREAT documentation that combines things well (the API docs contain concise math theory / formular / explanations AND usage examples), take a look at some of the Pytorch docs: https://pytorch.org/docs/stable/generated/torch.nn.Conv2d.html https://pytorch.org/docs/stable/generated/torch.nn.Conv2d.ht...
- infogulch 4y ago
  I disagree that writings for all these audiences should be dumped into a single disorganized pile. If I'm looking for API docs I don't want to parse through your contrived how-to combined with a shallow tutorial combined with a long treatise on your principles, just give me the damn API docs. Writing with a specific audience in mind is vital to get good results. That said, I'll agree that these should be interlinked. A tutorial that doesn't ever link to practical how to's is terrible, and please include references to theory in your api docs so I can gain a deeper understanding when the design doesn't make sense to me, etc etc. It's easier to write and read when you are assuming the audience of a particular work; you can switch roles when you click on a how-to article, but trying to inhabit all personas at once is exhausting and unproductive.
  - catchclose8919 4y ago
Wowfunhappy 4y ago
Wouldn't all of those audiences still need to know the what, why, and how? In different amounts, sure, but they're all still important.

rsolva 4y ago

The same excellent documentation framework is also available on this company-independent website: diataxis.fr

alipitch 4y ago
Thanks! Also checked the github site. https://github.com/evildmp/diataxis-documentation-framework https://github.com/evildmp/diataxis-documentation-framework
catchclose8919 4y ago
...this is questionable advice that goes against the interest of programmers having stuff to do - we're not segmented into audiences. We want multi-level docs combined/spliced/interwoven together so we can get our work done without wasting gandalfing the docs. > While redesigning the Cloudflare developer docs ...oh, so this is the reason for CF's docs totally uncomprehensible and confusing mess. They've made getting to anythin so comfusing that AWS seems a breath of fresh air in comparison. I dunno, maybe other peoples' brains are wired totally different than mine, but boy, these new fever of "writing better docs" seems to produce the exact opposite effects whenever applied. The few enojoyable docs nowadays seem to be written by old-school unixy geeks and/or people that are not programmers or worse, "documentation developers": physicists, mathematicians, biologists, quants, data analysts etc. seem to do a nice job when they have the time.

drothlis 4y ago

Just watched Daniele's talk. Brilliant, practical advice. Thanks so so much for the link.

catchclose8919 4y ago

> - the theorist (explanations) Further it's explained that this is where the "understanding" bit comes in. Ugh, so this school of thought is where some of the terrible modern documentation comes from... I want the explanations/understanding first COMBINED with a minimal how-to guide serving as illustration for the explanation. Then a quick link to an API reference that INCLUDES snippets of explanations and usage examples (that you'd find in tutorials or how-to guides). Separating thinking about documentation this way leads to horrible documentation where you start with dumbed-down tutorials missing lots of crucial information, and then you have to put in tons of unnecessary effort putting disparate things toget ther in your head. FFS, programmers are rarely students since most of what we learn is learning-on-the-job and never chefs or theoreticians. Tutorials always waste your time so you'd prefer to start with something much denser... only that the only thing denser you easily find are the API docs, and you lack the explanations to understand them and usage exmaples so you have to hunt them for yourself... yuck. As an example of GREAT documentation that combines things well (the API docs contain concise math theory / formular / explanations AND usage examples), take a look at some of the Pytorch docs: https://pytorch.org/docs/stable/generated/torch.nn.Conv2d.html https://pytorch.org/docs/stable/generated/torch.nn.Conv2d.ht...

infogulch 4y ago
I disagree that writings for all these audiences should be dumped into a single disorganized pile. If I'm looking for API docs I don't want to parse through your contrived how-to combined with a shallow tutorial combined with a long treatise on your principles, just give me the damn API docs. Writing with a specific audience in mind is vital to get good results. That said, I'll agree that these should be interlinked. A tutorial that doesn't ever link to practical how to's is terrible, and please include references to theory in your api docs so I can gain a deeper understanding when the design doesn't make sense to me, etc etc. It's easier to write and read when you are assuming the audience of a particular work; you can switch roles when you click on a how-to article, but trying to inhabit all personas at once is exhausting and unproductive.
- catchclose8919 4y ago

Wowfunhappy 4y ago

Wouldn't all of those audiences still need to know the what, why, and how? In different amounts, sure, but they're all still important.