- Diátaxis ist ein Konzept, das einen systematischen Ansatz für das Verfassen technischer Dokumentation bietet. Dieser Ansatz beginnt mit einem systematischen Verständnis der Bedürfnisse von Dokumentationsnutzern und schlägt Herangehensweisen an Inhalt, Struktur und Form vor.
- Diátaxis, abgeleitet aus dem Altgriechischen, identifiziert vier klar umrissene Bedürfnisse und die dazu passenden Dokumentationsformen: Tutorials, How-to-Guides, technische Referenz und Erklärung. Es wird vorgeschlagen, Dokumentation entsprechend dieser Struktur der Bedürfnisse zu organisieren.
- Diátaxis löst Fragen rund um den Inhalt der Dokumentation (was geschrieben werden soll), den Stil (wie es geschrieben werden soll) und die Struktur (wie es organisiert werden soll).
- Es ist nicht nur für Dokumentationsnutzer wertvoll, sondern auch für Autoren und Maintainer. Es ist leichtgewichtig, leicht zu verstehen und einfach anzuwenden. Es erzwingt keine Implementierungsbeschränkungen und bietet aktive Prinzipien zur Verbesserung der Dokumentationsqualität.
Inhalt
-
Diese Website ist in zwei Hauptbereiche gegliedert, die beim Anwenden und Verstehen von Diátaxis helfen.
- Hier anfangen. Diese Seiten helfen dabei, den Ansatz unmittelbar und konkret zu verstehen.
- Diátaxis anwenden
- Tutorials
- How-to-Guides
- Referenz
- Erklärung
- Kompass
- Workflow
- Dieser Bereich untersucht die Theorie und die Prinzipien von Diátaxis tiefer und vermittelt ein Verständnis der zugrunde liegenden Bedürfnisse.
- Diátaxis verstehen
- Grundlagen
- Karte
- Qualität
- Tutorials und How-to-Guides
- Referenz und Erklärung
- Komplexe Hierarchien
- Hier anfangen. Diese Seiten helfen dabei, den Ansatz unmittelbar und konkret zu verstehen.
-
Diátaxis ist ein in der Praxis bewährtes Prinzip. Es wurde in Hunderten von Dokumentationsprojekten erfolgreich übernommen.
- Bei Gatsby wurde das Diátaxis-Framework beim Umbau der Open-Source-Dokumentation als zentrale Ressource verwendet. Die vier Quadranten helfen dabei, die Ziele der Nutzer für jede Dokumentationsart in den Vordergrund zu stellen.
- Bei der Neugestaltung der Cloudflare-Entwicklerdokumentation wurde Diátaxis zum Polarstern der Informationsarchitektur. Indem bei der Entscheidung über die Platzierung neuer Inhalte auf das Framework Bezug genommen wurde, wurde die Dokumentation sowohl für Leser als auch für Mitwirkende klarer.
1 Kommentare
Hacker-News-Kommentare
Ein Nutzer merkt an, dass die wichtige Erkenntnis darin besteht, nicht alle Informationen auf einmal vermitteln zu müssen. Es sei nützlich, Informationen für unterschiedliche Leser auf verschiedene Weise aufzubereiten.
Es wird erklärt, dass sich der Dokumentationsfluss verbessert habe, nachdem das Diátaxis-Framework auf die Sequin-Dokumentation angewendet wurde. Allerdings wird auch erwähnt, dass die Diátaxis-Dokumentation selbst etwas schwer zugänglich und weitschweifig sei.
Verfasser technischer Dokumentation erwähnen, dass Diátaxis DITA ähnlich sei. Es wird jedoch erklärt, dass dabei die Bedürfnisse der Nutzer übersehen werden können und Informationen für die Wiederverwendung in kleine Teile zerlegt werden müssen.
Ein Nutzer, der eine SwiftUI-App entwickelt hat, findet, dass moderne technische Dokumentation schlecht behandelt wird, und argumentiert, dass Dokumentation sowohl aus Sicht der Maintainer als auch der Nutzer gedacht werden müsse.
Es wird erwähnt, dass Diátaxis für die Strukturierung von Dokumentation nützlich sei, bei zu strikter Anwendung aber zur Falle werden könne.
Es wird erklärt, dass der eigentliche Wert von Diátaxis darin liege, die Art des Dokumentierens zu vereinfachen. Wichtig sei, Dokumentation an die jeweiligen Bedürfnisse der Nutzer anzupassen.
Es wird erwähnt, dass die Grafik von divio intuitiver sei, Diátaxis aber umfassendere Dokumentation biete.
Es wird erklärt, dass sich die technische Dokumentation nach der Einführung von Diátaxis stark verbessert habe und dass Seitenverantwortung sowie regelmäßige Reviews zu erfolgreicher Dokumentation beigetragen hätten.
Es wird erwähnt, dass das Diátaxis-Framework eine einfache und leicht verständliche Struktur bietet und deshalb für das Schreiben technischer Dokumentation nützlich sei.
Jemand schreibt gerade die Dokumentation für Logdy mit Diátaxis und bittet um Meinungen dazu, ob diese Methode für die Dokumentation von Softwareprodukten nützlich ist. Es wird erklärt, dass sich über Blogposts die Produktnutzung wirksam vermitteln ließ.