> - 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.ht...

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.

> trying to inhabit all personas at once is exhausting

There's no personas, developers don't have three different brains they keep in the fridge and swap the ones in their head with.

Just admit that sure, interweaving information to get good quality docs is exhausting. And that we invented this "write for an audience" crap to simplify the work of the writers - "we're lazy or we have limited resources for writing docs, that's why we're doying it this way".

It's the same for writers and journalist, the "write for a specific audience" trick is way to lower the effort needed to get reviews / publishers' attention / clicks / views / shares etc. You do it when you're getting started if you ever want to get started I guess. But large scale it produces shallow literature, hard to fact check or contextualize journalism etc.

You do it for yourself (the writer) or to save resources for your companies (sure, interwoven/mixed docs are hard to maintain - I'm not even sure how eg. Pytorch's team manages to do that, but probably being the leading ML frameworks attracts top talent from the whole planet to one open-source project so it's doable for them...). But don't sell the bs that you're doing the reader/consumer any service, keept it hones to yourself and others!

Also

> a single disorganized pile

Nobody proposes a "single disorganized pile". Sure, it's hard to eg. put bite-sized examples + condesed 'why' explanations into API docs and to maintain such docs, but it's doable - in the ML community some people use notebooks for docs wiriting and sometimes even for development by generating the code from them (sure, this is utterly extremist and I don't like it myself, but it works for some), some kind of renaissance of "literate programming".

I don't say we revive literate programming, but going haf-way between that and "a disorganized pile" is what I meant.

I agree, the tutorial and the explaination should go in tandem. Start slow and help the users to form the right images in their heads in the beginning.

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

...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.

Thanks! Also checked the github site. https://github.com/evildmp/diataxis-documentation-framework

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.

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