Diátaxis - a systematic approach to technical documentation authoring

[amotl]

Pitch

A proposal to better/softly adhere to paradigms of Diátaxis going forward. ✨

• [en] https://diataxis.fr/
• [de] https://fachglossar.platinus.at/docs/Glossar/D-Glossar/Diataxis-Framework/

[kneth]

First step is that @surister will give a short presentation or pitch on Diátaxis

[amotl]

Based on definitions in Diátaxis (thanks @surister!), we've tuned down many tutorials, which are effectively just quick walkthroughs, thus renamed them to usage.md instead of tutorial.md. Let us know if we missed any, or if you would like to see individual articles to be promoted again.

• Harmonize leaf node page names: index.md vs. tutorial.md vs. usage.md #171
• Naming things: s/tutorial/usage/ #347

[amotl]

We started to softly implement Diátaxis ideas by regrouping existing content into the proposed shapes, based on its ingredients.

• Authoring guidelines: Mention "Diátaxis" approach crate-docs#117
• Naming things: Per Diátaxis, using "Guides" is not applicable. Use "Handbook" instead. crate-docs-theme#635
• Diátaxis: Index how-to guides and tutorials #364
• Diátaxis: Add "Explanations" section #431

What's still missing is to improve the quality of the articles themselves.

• https://github.com/crate/tech-writing/issues/106