Comment by mmyrte

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