- Ausgehend von der Annahme, dass technische Dokumentation je nach Situation für Nutzer unterschiedliche Rollen erfüllen muss, ist Diátaxis ein Ansatz, der Inhalt, Struktur und Form gemeinsam ordnet
- Es teilt Nutzerbedürfnisse in vier Kategorien ein und ordnet sie den Dokumenttypen tutorials, how-to guides, technical reference, explanation zu
- Es ist nicht nur eine einfache Klassifikationstabelle, sondern eher ein Framework für Dokumentationsdesign, das behandelt, was man schreibt, wie man es schreibt und wo man es platziert
- Auch Autoren und Maintainer können die Qualität von Dokumentation leichter beurteilen; Vorteile sind, dass der Ansatz leichtgewichtig, intuitiv und nicht an eine bestimmte Implementierungsweise gebunden ist
- Wie die Beispiele von Vonage, Gatsby und Cloudflare zeigen, kann er Teams, die Auffindbarkeit und Informationsarchitektur ihrer Dokumentation verbessern wollen, als praktischer Maßstab dienen
Die 4 Dokumenttypen nach Diátaxis
- Diátaxis ist eine Denkweise und praktische Methode zum Erstellen und Betreiben technischer Dokumentation
- Ausgangspunkt ist das Verständnis der Bedürfnisse der Dokumentationsnutzer; daraus werden Prinzipien für Inhalt, Architektur und Form abgeleitet
- Dokumentationsanforderungen und -formate werden in vier Kategorien unterteilt
-
tutorials
-
how-to guides
-
technical reference
- explanation
- Auch die Dokumentation selbst sollte um diese vier Bedürfnisse herum organisiert werden, und Diátaxis behandelt dabei gemeinsam drei Fragen
- content: Was soll geschrieben werden?
- style: Wie soll es geschrieben werden?
- architecture: Wie soll es organisiert werden?
-
Anwendbarkeit für Autoren und Maintainer
- Diátaxis ist ein Ansatz, der nicht nur Dokumentationsnutzern, sondern auch Autoren und Maintainern hilft
- leichtgewichtig und einfach zu verstehen
- intuitiv anwendbar
- erzwingt keine Implementierungsbeschränkungen
- bietet Qualitätsprinzipien, anhand derer Maintainer ihre eigene Arbeit beurteilen können
- Die Prinzipien wurden auf Basis ihrer erfolgreichen Einführung in Hunderten von Dokumentationsprojekten zusammengefasst
Beispiele aus realen Dokumentationsprojekten
- Greg Frileux von Vonage bewertet Diátaxis so, dass sich damit eine interne Dokumentationssammlung erstellen ließ, die Nutzer gern verwenden und zu der Mitwirkende gern etwas hinzufügen
- Gatsby gab an, beim Umbau seiner Open-Source-Dokumentation das Diátaxis-Framework als zentrale Ressource genutzt zu haben; die vier Bereiche hätten geholfen, die Nutzerziele jedes Dokumenttyps zu priorisieren
- Cloudflare nutzte Diátaxis bei der Neugestaltung der Cloudflare developer docs als Maßstab für die Informationsarchitektur und zog das Framework heran, um zu entscheiden, wo neue Inhalte eingeordnet werden sollten
1 Kommentare
Hacker-News-Kommentare
Auch aus der Perspektive von jemandem, der nicht professionell schreibt, ist die wichtigste und grundlegendste Einsicht, die ich hier mitgenommen habe – unabhängig von den Details –, dass man nicht alles genau einmal sagen muss
Bevor ich auf diesen Gedanken gestoßen bin, habe ich mich selbst verheddert, weil ich dachte, ein einzelner Textfluss müsse die Rolle des „gesamten Dokuments“ erfüllen
Schon die Erkenntnis, dass man dieselbe Information für unterschiedliche Leser auf verschiedene Weise formulieren darf, hilft enorm
Da der Leser den gemeinsamen Nenner zwischen den Beispielen findet, ist es weniger mehrdeutig, als nur mit einem einzigen Beispiel zu erklären
Autoren wie Salomo in den biblischen Sprüchen nutzen diese Technik ebenfalls häufig
Im Abstract schreibt man etwa: „Diese Arbeit zeigt, dass X gilt, indem sie Y mit Z evaluiert“, in der Einleitung erklärt man dann, warum das Problem von A wegen B wichtig ist, dass der Aspekt X aber übersehen wurde und dass eine Evaluation von Y – anders als Z – reale Herausforderungen sichtbar macht, und fasst dann erneut zusammen: „Kurz gesagt ist Y wegen X besser als Z“
Auch im Abschnitt zu verwandten Arbeiten kann man anschließen, dass der Ansatz Z zwar etwas verbessert hat, aber – wie später gezeigt wird – nicht ausreicht; so kreist man in jedem Abschnitt weiter um die Kernbotschaft und greift sie erneut auf
Ich habe dieses Framework vor zwei Wochen auf die Dokumentation von Sequin angewendet, und allein die Tatsache, dass es eine Struktur gibt, war schon sehr hilfreich
Der Dokumentationsfluss ist jetzt deutlich besser, und weil klar ist, was wohin gehört, ist es auch leichter, neue Dokumentation hinzuzufügen und zu pflegen
Ironischerweise war die Diátaxis-Dokumentation selbst allerdings etwas schwer zugänglich und weitschweifig, sodass ich erst nach mehrmaligem Lesen ein Gefühl dafür bekommen habe
Als ich es dem Team erklärte, verglich ich es mit dem Kauf eines Küchengeräts wie eines Schnellkochtopfs: Zuerst schaut man sich einen Schnellstart (Tutorial) an, um grob zu sehen, wie man von A nach B kommt; dann sucht man nach einer Anleitung dafür, wie man ein bestimmtes Lieblingsgericht zubereitet; wenn Detailfragen auftauchen, schaut man in den Referenzunterlagen die genauen Garzeiten für verschiedene Bohnensorten nach; und wenn man sogar verstehen will, warum Druck die Garzeit verändert oder wie die Sicherheitsmechanismen funktionieren, liest man die Erklärung dazu
Lustigerweise war unsere Dokumentation komplett umgekehrt aufgebaut und begann mit Erklärungen wie „How Sequin Works“
Der natürliche Impuls von Engineers ist, zuerst die Funktionsweise und die Gründe für das Design zu erklären, um ein mentales Modell zu vermitteln – aber die Leute haben weder die Zeit noch die Geduld dafür
Es ist besser, sie über den Ablauf Schnellstart → How-to → Referenz an die Welt heranzuführen und erst dann, wenn man ihr echtes Interesse gewonnen hat, mit Erklärungen den Ansatz zu vermitteln
https://sequinstream.com/docs
Oft werden Dokumentationen entweder vage durch Unsinn wie „innovative Synergie-Erfahrung“, als ob sie sich schämen würden anzuerkennen, dass das Firmen-Tool einfach nur ein Tool ist, oder sie gehen ins Überkonkrete, bevor sie überhaupt behandeln, warum dieses Produkt existiert
Allerdings tauchte in der Dokumentation ständig CDC auf, und ich musste erst nach der Definition suchen. Ich habe in meiner Laufbahn mehrfach CDC implementiert, war mit dem Akronym aber nicht vertraut
Der Fluss ist letztlich die Wahl des Lesers; mein Kopf funktioniert so, dass ich zuerst die Gesamterklärung will und danach nach How-tos und Tutorials suche
Aus Sicht eines Technical Writers ist Diátaxis DITA ähnlich: https://www.oxygenxml.com/dita/1.3/specs/archSpec/base/information-typing.html
Solche Systeme können jedoch verfehlen, was Nutzer tatsächlich brauchen
Wenn technische Dokumentation nur innerhalb einer Dokumentationsplattform genutzt wird, kann Diátaxis langfristig gut passen; wenn dieselbe Information aber an vielen Stellen wie UI, Dokumentationsportal und Mobile App verwendet werden kann oder sogar sollte, muss man die Information eventuell in kleinere Teile zerlegen und auf verschiedene Arten zusammensetzen
Das nennt man Content Reuse und bedeutet, denselben Inhalt an mehreren Stellen zu verwenden
Ein Ansatz zum Schreiben und Redigieren von Informationen für Content Reuse wird im Konzept „every page is page one“ beschrieben: https://everypageispageone.com/the-book/
Wenn Ressourcen und Zeit vorhanden sind, würde ich in der Startphase des Projekts UX-Research empfehlen. So vermeidet man später eine erstickende Situation durch ein zu restriktives Informationsmodell
Nielsen/Norman hat in diesem Bereich ebenfalls viel geforscht und macht interessante Vorschläge zur Lösung entsprechender Probleme: https://www.nngroup.com/articles/information-foraging/#toc-what-is-information-foraging-2
DITA unterscheidet zwar zwischen Thementypen wie Task, Reference und Concept, aber Tutorials oder Solution Guides sind Kombinationen solcher Thementypen
Hier scheint der Fokus eher auf größeren Artefakten als auf einzelnen Topics zu liegen
Ich frage mich auch, ob Komplexität für dich kein Problem ist, weil du so tief in DITA drinsteckst
Wenn man Inhalte in wiederverwendbare Bausteine zerlegt und sie mit DITA- oder DocBook-Semantik auszeichnet, scheint das für große Sprachmodelle viel leichter „verständlich“ zu sein, aber dazu habe ich noch keine Daten gesehen
Heutzutage gibt es bessere Wege, Dokumentation zu schreiben, als sich mit XSL/FO und seinen Verwandten herumzuschlagen
Im Bereich des Verfassens technischer Dokumentation ist das bereits sehr beliebt und kommt einem Standard ziemlich nahe
Allerdings wird das manchmal zu weit getrieben, sodass auf Dokumentationsseiten buchstäblich nur noch diese vier Kategorien stehen, was meistens nicht gut funktioniert
Vor allem ist es nützlich, damit Autorinnen und Autoren die Haltung beibehalten wie: „Das ist ein Guide, also sollten wir nicht lehren wollen, sondern uns darauf konzentrieren, zum Ergebnis zu kommen“
In der Praxis sind zu starre Grenzen nicht wünschenswert, und ein bisschen Tutorial in einem Guide ist auch in Ordnung
In der Praxis hakt dieser Ansatz meiner Ansicht nach dort, wo die Verbindungen zwischen den Quadranten fehlen
Wenn in einem Software-Framework ein Guide zum Beispiel nicht auf die Referenz zu den konkreten Klassen oder Methoden verlinkt, die man am Ende verwenden muss, wird es viel schwerer, den umgebenden Kontext zu erkunden
Einige konkrete Framework-Dokumentationen haben die Quadranten auf diese Weise getrennt, und genau das ist einer der größten Ärgernisse an diesen Dokumentationen
Wenn keine anderen Fachleute da sind, ist es für Anfänger womöglich besser, Regeln strikt zu befolgen, als „einfach selbst das Richtige tun zu wollen“
Anfänger haben per Definition nicht die nötige Expertise für solche Urteile, und mit wachsender Erfahrung beginnt man zu erkennen, an welchen Stellen man von festen Regeln abweichen sollte
Das ist ähnlich wie der Unterschied zwischen Hausmannskost nach Kochbuch und einem Profi-Koch, der Zutaten nach Gefühl und Geschmack in den Topf wirft
Ich habe aber schon mit jemandem gearbeitet, der darauf bestand, Regeln wörtlich zu befolgen, und meinte, in einem Tutorial dürfe nicht einmal ein einziger erklärender Satz stehen
Genau darin liegt die Gefahr solcher Systeme
Das ist ähnlich wie Programmierprinzipien wie „ändere keine globalen Variablen“ oder „halte Funktionen kurz“
Man muss es nicht perfekt treffen, aber für die meisten ist es besser, sich in diese Richtung zu bewegen als in die entgegengesetzte
Daraufhin bat ich Claude, den oberen Abschnitt nach Diátaxis zu klassifizieren, und es antwortete, dass es sich überwiegend um Erklärung handle, mit einigen eingemischten Referenzelementen, und dass das nach Diátaxis-Maßstäben nicht ideal sei
Besser wäre laut der Antwort eine Trennung in einen Abschnitt, der rein das Konzept und die Bedeutung von Hyperparameter-Tuning erklärt, und einen separaten Referenzabschnitt, der die verfügbaren Tools und Methoden auflistet
Anschließend wurde aber auch zusammengefasst, warum dieser integrierte Ansatz im Kontext eines Benutzerhandbuchs gut funktioniert: Er folgt dem tatsächlichen Lernfluss der Menschen, verbindet Konzepte direkt mit der Umsetzung, entfaltet sich schrittweise von Grundkonzepten zu komplexeren Tools und verknüpft Theorie mit Praxis, wodurch praktischer Nutzen entsteht
Nachdem ich gerade erst meine erste SwiftUI-App veröffentlicht habe, habe ich stark das Gefühl, dass mit Dokumentation in der modernen Tech-Industrie viel zu schlampig umgegangen wird
Mir fehlt die Arbeit der großartigen technischen Redakteurinnen und Redakteure, die Apple entlassen hat, wirklich sehr, und Apple-Ingenieurinnen und -Ingenieure schreiben wirklich schlechte Dokumentation
Bei „dogmatischen“ Ansätzen bin ich allerdings immer vorsichtig. Es entsteht leicht eine „Priesterkaste“, die auch dann nicht nachgibt, wenn die Realität es verlangt
Die Leute, die diese Lehre ursprünglich geschaffen haben, setzen sie oft hervorragend ein, aber die nachfolgenden „Priester“ ruinieren sie und machen aus dem Ansatz einen Fluch
Viele gute Ideen sind durch übermäßig starre Anwendung ruiniert worden. Man muss sich nur ansehen, was aus „Agile“ geworden ist
Dokumentation hat im Grunde zwei Gesichter: die der Maintainer und die der Nutzer, und ihre Anforderungen unterscheiden sich stark, weshalb sich wahrscheinlich völlig unterschiedliche Teams darum kümmern sollten
Es gibt zwar das Problem, dass mehrere Dokumentationsorte auseinanderlaufen, aber entscheidend ist das Ergebnis
Wenn man mehrere Instanzen effektiv synchron halten kann, ist die Dokumentation für ihre Zielgruppe effektiv und nützlich
Selbst perfekt formatierte und synchronisierte Dokumentation ist wertlos, wenn sie niemand liest
In SNL spielte Phil Hartman The Anal-Retentive Chef, der so viel Zeit auf die Vorbereitung verwendete, dass er die eigentliche Kochdemonstration nicht mehr schaffte, und genau so etwas sehe ich im technischen Bereich oft
Toolchains und Bibliotheken sind perfekt, aber in der Praxis nicht wirklich nutzbar
Dokumentation ist ein Gemisch aus vielen Bereichen: menschliche Natur und Psychologie, Grafikdesign, Informationsarchitektur, technische Infrastruktur sowie Publishing und Distribution
In den meisten Projekten wird Dokumentation als nachträgliche Aufgabe behandelt, aber meiner Meinung nach sollte sie schon in der Anforderungsphase ein erstklassiger Aspekt sein
Wie tief man sich in Dokumentationsstrukturen eingraben kann, ist nach oben offen, aber es dient hervorragend als Stützräder, bis man merkt, wo etwas undicht wird
Das klingt so, als würde ein allgemeines Missverständnis oder eine fehlerhafte Anwendung einer guten Idee die Idee selbst verderben
Stattdessen steckt darin Erfahrung, die man aus der realen Anwendung gewinnt. Wenn die ursprüngliche Idee in Wahrheit nicht gut war, wird damit nur eine Illusion zerstört, und schlechte Beispiele machen durch ihr Scheitern sichtbar, welche Mehrdeutigkeiten zu Fehlinterpretationen führen können, sodass man die Idee weiter verfeinern kann
Wenn sich allerdings viele Menschen an schlechte Umsetzungen gewöhnen, kann die Popularität der Idee sinken und damit auch die Nachfrage nach ausgereiften Implementierungen
Das ist weniger eine Degeneration der Idee selbst als eher eine Tragödie der Anti-Allmende
Diátaxis eignet sich hervorragend zur Strukturierung von Dokumentation, aber sein eigentlicher Wert liegt darin, die Art und Weise zu vereinfachen, wie man Dokumentation schreibt
Es hilft dabei, sich von der Vorstellung zu lösen, alles in ein einziges „perfektes Dokument“ pressen zu müssen, und stattdessen anzuerkennen, dass verschiedene Nutzer unterschiedliche Bedürfnisse haben
Tutorials sind zum Lernen durch Nachmachen da, Guides zur Lösung eines konkreten Problems, Referenzen zum schnellen Nachschlagen und Erklärungen dazu, dem „Warum“ nachzugehen
Allein diese Klarheit kann schon dazu führen, dass man nützliche Dokumentation schreibt
Trotzdem wird jedes System zur Falle, wenn man sich zu starr daran festhält
Oder gibt es ein integriertes Paradigma?
In unserer Organisation verwenden wir diesen Ansatz, und seit seiner Einführung hat sich die technische Dokumentation auf ein völlig anderes Niveau gehoben
In Kombination mit Seitenverantwortung und regelmäßigen Reviews durch die jeweiligen Seitenverantwortlichen ist das die einzige wirklich erfolgreiche technische Dokumentationsarbeit, die ich bisher gesehen habe
Ich finde die von Divio verwendete Grafik deutlich intuitiver: https://docs.divio.com/documentation-system/
Allerdings scheint die Diátaxis-Seite die einzelnen Bedeutungen umfassender zu dokumentieren.
Ich denke, die Überarbeitung von Divio auf Diataxis.fr ist grafisch weniger unruhig, aber im Wesentlichen dieselbe wie die bei Divio verwendete.
Ich habe die beiden Ressourcen im Hinblick auf die Ideen, die sie im Kontext ihrer jeweiligen Websites vermitteln, im Grunde als dasselbe Dokument betrachtet.
Ich würde gern wissen, was daran intuitiver ist.
Die Idee gefällt mir, und ich hatte das Glück, den Urheber ein paar Mal auf der PyConUK zu treffen. Ein talentierter und sehr freundlicher Mensch.
Allerdings bin ich zurückhaltend, was eine so strikte Trennung der verschiedenen Bereiche von Dokumentation angeht.
In irgendeinem Sprint wurde mir einmal gesagt, dass die Dokumentation, die ich vorbereitete, nicht akzeptabel sei, weil sie mehrere Formen vermischte. Nur der Vollständigkeit halber: Das war nicht Daniele.
Ich will mich nicht auf Autorität berufen, aber ich habe über 20 Jahre als Lehrer gearbeitet und habe ein gewisses Gespür dafür, wie man Dinge so erklärt und Lernen so aufbaut, dass Menschen etwas erledigen und gleichzeitig Verständnis aufbauen können.
Solange es nicht in völlige Starrheit ausartet, ist das ein hervorragendes Werkzeug, um darüber nachzudenken, wie man Dokumentation erstellt und was jede Art von Dokument leisten soll.
Bei Dokumentationsbeispielen, etwa bei numpy, sehe ich oft, dass man deutlich bessere Beispiele auswählen könnte als solche, die wie „Magie aus dem Himmel gefallen“ wirken.
Ein einziges gut gewähltes Beispiel kann enorm viel Lernwert bieten, indem es die Verwendung zeigt und zugleich Randfälle oder Fallstricke vermittelt.
Theoretisch halte ich es für richtig, aber ich finde es schwer, dem zuzustimmen. Die Begriffe liegen zu nah beieinander.
Für mich fühlen sich „Tutorial“, „How-to-Guide“ und „Erklärung“ praktisch fast wie Synonyme an.
Wenn ich tiefer darüber nachdenke, sehe ich schon, dass jede Kategorie ihre Berechtigung hat, aber semantisch liegen sie so nah beieinander, dass mein Kopf den Unterschied nicht erkennt.
Wenn ich wissen will, wie etwas funktioniert, und „Tutorial“ und „How-to-Guide“ sehe, weiß ich nicht, worauf ich klicken soll, und klicke einfach auf das erste.
Es kann auch eine nützliche Übung sein, Begriffe zu finden, die für dich besser passen.
Oder du kannst es über die Unterscheidung Handlung/Kognition verstehen, also „tun vs. denken“, sowie Aneignung/Anwendung, also „beim Lernen vs. bei der Arbeit“.
Es gibt auch eine eigene Seite zur Unterscheidung zwischen Tutorials und How-to-Guides: https://diataxis.fr/tutorials-how-to/
Eine der einfachsten Unterscheidungen ist: Ein Tutorial ist etwas, das man nicht auf Stack Overflow machen kann.
Ein Tutorial folgt einem vom Lehrenden festgelegten Lehrplan und füllt Lücken, von denen die Lernenden noch nicht einmal wissen, dass sie sie haben.
Auf Stack Overflow muss man eine Frage stellen, aber ein Tutorial ist Material für Menschen, die noch nicht einmal wissen, was sie fragen sollen.
Es gibt zwar auch viele beliebte Fragen dazu, wie man einfache Aufgaben erledigt, aber damit es in dieses Format passt, muss man eine Frage stellen statt nur vage um Hilfe zu bitten: https://meta.stackoverflow.com/questions/284236
Die Diátaxis-Dokumentation erklärt die Unterschiede ziemlich effizient: Tutorials sind lernorientierte Erfahrungen, How-to-Guides zielorientierte Anleitungen, Referenzmaterial informationsorientierte technische Beschreibungen, und Erklärungen verständnisorientierte Diskussionen.
„Tutorial“ in diesem System kann man als Fachbegriff lesen und nicht als Alltagswort.
Das ist ähnlich wie bei „depression“ in der Psychologie, das auch nicht exakt dasselbe bedeutet wie im alltäglichen Sprachgebrauch.
Immer noch besser, als sie Tutorial Typ I–IV zu nennen.
Eine Vorlesung ist eine Erklärung, ein Tutorial oder Praktikum ist eine angeleitete Erfahrung, und ich muss dabei an Microsofts fiktive Firma Contoso denken.
Einen How-to-Guide braucht man, wenn man nach einer Lösung sucht oder ChatGPT fragt, und Referenzmaterial ist so etwas wie ein Thesaurus, eine Enzyklopädie oder ein Benutzerhandbuch.
Videospiele haben eingebaute Tutorials, aber für schwierige Rätsel braucht man trotzdem noch Komplettlösungen, und die Tastenbelegung schaut man im Referenzmaterial nach.