Diátaxis

I've also found these guidelines helpful:

1. In general, do whatever Wikipedia does. e.g., start with a one-sentence definition, then a couple paragraphs of summary, then go into short specified sections, and keep links to the "Citations" at the end. It's been refined for 25 years, it's older than most of your engineers, it's 50+% correct by default.

2. Keep every section to one screenful. If your reader can't see a headline, they get lost.

3. Put a funny picture at the top of the page. Or at least something off Wikimedia Commons.

4. Don't spend a lot of time writing anything. And don't use AI. The AI doesn't know what's inside your head. You yourself have an inkling. The longer you write, the further you'll get. Just write one short thing at a time and refactor aggressively later. Never throw shit over a fence blind. Nobody reads shit that's been flung over a fence.

Steven King said writing is telepathy. All mediated communication sits on a Pareto trade-off with face-to-face communication. Media is always less interactive with slower iterations. You need to figure out exactly what your audience needs, right when they're reading, and write just that, knock 'em dead, and leave. Don't add detail. They'll ask if they need detail.

I was not familiar with Diataxis, and as I was reading through the webpage, I kept wondering if there were any concrete examples. I love cooking, and it was interesting to see that some of the insights of the whole philosophy used teaching how to cook as an example.

I read a lot of cookbooks, and interestingly enough, I never stopped thinking about what makes a good cookbook (except for its recipes). Diataxis answers that in a way. Indeed, the best cookbooks I have read in some way or another followed Diataxis.

Hypotaxis: arranging under

Parataxis: arranging alongside

Diátaxis: arranging across

[flagged]

I am sure that this exists for other ecosystems as well - rustdoc, Documenter.jl and Sphinx seem to support this - but my experience lies in R: three of the Diátaxis categories map quite nicely onto R package constructs:

- Tutorials are implemented as "vignettes", executed on package validation - How-Tos are attached in roxygen documentation chunks, likewise executable by default - execution disabled when expensive or to avoid side effects. - Reference is implemented in a TeX or Markdown format, commonly parsed by roxygen

The only thing that's missing is a canonical way of documenting implementation rationale. Having the documentation outside the repo worked before LLMs, but there was always that weak point of code drifting away from the documentation...