3 ms·

I love whenever this comes up. It’s a great framework for thinking about and writing docs. It’s hard to keep documentation up to date, however, and I find that

I love whenever this comes up. It’s a great framework for thinking about and writing docs. It’s hard to keep documentation up to date, however, and I find that items like tutorials and reference materials (unless generated off versioned code) can drift pretty far over time. A feature I like in concept that notion introduced with wikis ages ago was a “verification” timestamp, where you specify a timeframe after which the doc owner has to reconfirm that the doc is up to date. A bit too easy to rubber stamp, unfortunately, but maybe if it took the doc offline entirely without a more robust audit.

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 ago
  Sounds 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.
nneonneo 2mo ago
Something that Python gets right is that their entire docs site is versioned - select 2.7.18, for example, and you get the 2.7 docs right down to the tutorial. The Python development process is also very careful about keeping documentation up to date; the PEP process even requires an explicit "How to Teach This" section for proposals that add or change language features.

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

nneonneo 2mo ago

Something that Python gets right is that their entire docs site is versioned - select 2.7.18, for example, and you get the 2.7 docs right down to the tutorial. The Python development process is also very careful about keeping documentation up to date; the PEP process even requires an explicit "How to Teach This" section for proposals that add or change language features.