3 ms·
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á
by mmyrte 2mo ago
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...
- mmargenot 2mo agoSounds like good support for a few different paradigms. Python has pretty good autogenerated reference docs, but if you want more than markdownified docstrings it makes them as difficult to maintain as the other pillars. As a set, the pillars aren’t as neatly grouped in Python documentation tooling, but I typically differentiate how-to, tutorial, etc with type tags in Notion or other indexes that point to where each type of thing lives.