I recently learned of Diátaxis, described as “A systematic framework for technical documentation authoring”. It is a website with someone’s opinions about how to write good documentation (actually how to structure it), and I find it interesting. Basically it encourages authors to structure documentations in four categories (tutorials, how-to guides, references, explanations), and argues that they should be kept distinct. (See a slightly longer quote below.)
I wonder what people think, and if they have other pointers to recommend on how to write documentation. (Curiously there is much less content online about documentation writing than about code writing.)
Diátaxis divides documentation across two axes of knowledge: theory/practice , and acquisition/application .
Documentation therefore either contains theoretical knowledge or describes practical actions , and is concerned either with serving our acquisition or our application of knowledge. Hence the map, across which the four forms of documentation are laid out:
Note: I re-read parts of the 2018 OCaml Documentation Open Thread, which has a different general focus but also contains many useful comments!