Diataxis

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

• Tutorials: “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/

• Howto-Guides: “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/

• Reference: “Reference guides are technical descriptions of the machinery and how to operate it. Reference material is information-oriented.” https://diataxis.fr/reference/

• Erklärungen: “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:

• Code: Code, insbesondere einzelen Jupyter-Notebooks

• Dokumente: 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

• eXamples: 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.