# Diataxis


In der Software-Dokumentation wird zunehmend das Framework [Diátaxis](https://diataxis.fr/) eingesetzt. Experiment im WS 2022: Taugt Diataxis auch für die Strukturierung unserer Lernumgebung? Wir probieren es aus:

* {doc}`t`: "Tutorials are lessons that take the reader by the hand through a series of steps to complete a project of some kind. Tutorials are learning-oriented." <https://diataxis.fr/tutorials/>
* {doc}`h`: "How-to guides are directions that take the reader through the steps required to solve a real-world problem. How-to guides are goal-oriented." <https://diataxis.fr/how-to-guides/>
* {doc}`r`: "Reference guides are technical descriptions of the machinery and how to operate it. Reference material is information-oriented." <https://diataxis.fr/reference/>
* {doc}`e`: "Explanation is discussion that clarifies and illuminates a particular topic. Explanation is understanding-oriented." <https://diataxis.fr/explanation/>

Zusätzlich haben siche folgende Abschnitte als sinnvoll erwiesen:

* {doc}`c`: Code, insbesondere einzelen Jupyter-Notebooks
* {doc}`d`: Documents / Dokumente: Stellvertreter-Seiten, die Dokumente beschreiben, die nicht hier direkt im Skript gedruckt werden sollen:
  * allgemein alle Text-Corpora, CSV-Dateien etc.
  * insbesondere auch die CSV-Dateien, die wir für Kaggle Learn benötigen
* {doc}`x`: eXamples: Beispiele etc.


## Diataxis Beispiel "Kaffekochen"


Beispiel Kaffekochen:

* e_ (Erklärung, Explanation) stellt Grundlagen- und erweitertes Wissen bereit: Alles, was man über Kaffekochen wissen muss.
* h_ (Howto) enthält kurze Anleitungen, wie man mit bestimmten Geräschaften einen Kaffee kocht.
* r_ (Reference) enthält die Produktdatenblätter zu sämtlichen Kaffesorten, Gerätschaften etc.

Zusätzlich zu Diataxis haben wir:

* d_ (Dokumente, Documents) enthält Stellvertreter-Dateien für weitere (oft externe oder als print nur schwer darstellbare) Dokumente, die für das Kaffekochen relevant sind
  * z.B. Links oder recherchestrategien zur den Informationen zur Wasserhärte des örtlichen Wasserwerks
  * z.B. XML-Konfigurationsdateien für bestimte Kaffee-Vollautomaten
* x_ (eXamples) enthält ganz konkrete Beispiele von Kaffekoch-Ereignissen: Diese Sorte, diese Temperatur, diese Menge, dieses Gerät, dieser Vollrohrzucker passen gut zusammen
* c_ (Code): Software, Jupyter Notebooks - nicht unbedingt relevant fürs Kaffeekochen
* y_ (bibliographY): die Literatur

Ebenfalls in Diataxis enthalten:

* t_ empfiehlt Vorgehensweisen, mit welchen obenstehenden Dokumenten man das Kaffekochen erlernen kann.

Bis auf t_ sind alle Dokumente auf die Sache bezogen. t_ gibt dagegen an, wie man sich  Kenntnisse und Fertigkeiten bezüglich der Sache aneignen kann - und zwar mit Hilfe der anderen Dokumente.