Was ist eine Dokumentation?

Was ist eine Dokumentation?

Bevor wir tiefer in die technischen Aspekte der Erstellung einer Dokumentation einsteigen, möchten wir dir zunächst eine Definition geben, was eine Dokumentation eigentlich ist.

Wenn du im Internet nachschaust, findest du Definitionen wie diese:

Wie die obigen Beispiele zeigen, wird Dokumentation oft mit technischen Disziplinen in Verbindung gebracht. Viele Menschen haben von Softwaredokumentation gehört und die meisten von uns haben schon einmal die Erfahrung gemacht, einem Benutzerhandbuch zu folgen, um einen IKEA Pax Kleiderschrank zusammenzubauen oder etwas mit LEGO-Steinen zu bauen.

Auch wenn wir sie nicht als Dokumentationen bezeichnen, begegnen wir ihnen in vielen anderen Bereichen unseres beruflichen und täglichen Lebens. Best Practices bei der Arbeit gewährleisten die Qualität von Produkten und Dienstleistungen, Anleitungen helfen uns bei schnellen Lösungen und Online- oder persönliche Tutorials bieten uns die Möglichkeit, neue Fähigkeiten zu erlernen.

Hier ist unsere Definition von Dokumentationen:

Eine Dokumentation kommt in Form von Text, Illustration, Video oder Audio und zielt darauf ab, über Themen, Prozesse und Dienstleistungen zu erklären, zu lehren, zu führen oder zu informieren.

Inspiriert vom Diátaxis-Framework von Daniele Procida, gruppieren wir Dokumentationen in 4 Hauptkategorien:

• Erklärungen
• Tutorials
• Anleitungen
• Referenzen

An diesem Punkt fragst du dich vielleicht: „Was ist der Unterschied zwischen diesen 4 Kategorien? Ist das nicht irgendwie alles dasselbe?“

Lass uns dir ein klareres Bild geben.

Erklärungen

Erklärungen dienen dazu, über ein bestimmtes Thema oder einen Prozess zu informieren. Wir möchten ein größeres Bild zeichnen, das dem Benutzer ermöglicht zu verstehen, warum die Dinge so sind, wie sie sind. Das Ziel ist es nicht nur Fakten und Theorien zu präsentieren, sondern den Benutzer dazu anzuregen, über das gegebene Thema nachzudenken.

Erklärungen beinhalten nicht:

• Benutzerhandbücher
• Rezepte
• Tutorials
• Referenzabschnitte

Zum Beispiel liest du gerade eine Erklärung darüber, was Dokumentationen sind. Wenn du unsere Einführung weiterliest, wirst du mehr über Content-Management, Wissensmanagement und Datenmanagement im Kontext der Einrichtung, Erstellung und Verwaltung jeglicher Art von Dokumentation erfahren.

Du wirst einen Überblick über verschiedene Technologien, ihre Vor- und Nachteile und was sonst noch zu beachten ist, um eine professionelle Benutzererfahrung für die Nutzer deiner Software und die Verantwortlichen für die Dokumentation zu bieten. Diese Einführung sollte dir genügend Informationen geben, um über deine eigenen Dokumentationsbedürfnisse nachzudenken und die richtige Entscheidung für dein Projekt zu treffen.

Erklärungen können die folgenden Elemente enthalten:

• Einleitung - Gibt den Zweck an und gibt einen Überblick über die Diskussion.
• Definition - Formale Definition des Konzepts.
• Hintergrund - Bietet Geschichte und Kontext.
• Details - Erläutert verschiedene Aspekte des Konzepts.
• Visuals - Diagramme, Illustrationen, Beispiele, die Klarheit schaffen.
• Beziehungen - Verbindet Konzepte mit anderen Ideen und Ansätzen.
• Auswirkungen - Erforscht Effekte, Ergebnisse und Bedeutung.
• Zusammenfassung - Fasst die wichtigsten Punkte zum Konzept zusammen.
• Weiterführende Literatur - Zusätzliche Ressourcen, um mehr zu erfahren.

Tutorials

Ein Tutorial, oder anders gesagt eine Lektion, ist eine Lernerfahrung, die dem Benutzer hilft, Fähigkeiten und Wissen zu erwerben. Es geht darum, den Benutzer durch eine praktische Aktivität zu führen, die klare Erwartungen setzt und mit jedem Schritt des Tutorials sichtbare Ergebnisse liefert.

Wir möchten den Benutzer mit den Werkzeugen, der Sprache und den Prozessen in einer sicheren Umgebung vertraut machen. Das bedeutet, dass wir das Unerwartete eliminieren und einem konkreten und einzigen Weg folgen. Wir minimieren auch Erklärungen, da diese den Benutzer vom Tun ablenken. Stattdessen kannst du Links zu „Weiterlesen“-Abschnitten bereitstellen.

Jeder Benutzer wird durch dasselbe Tutorial verschiedene Aspekte lernen. Statt also zu fragen: „Was ist zu lernen?“ konzentrieren wir uns auf die Frage: „Was ist zu tun?“. Auf dem Weg etablieren wir eine Erzählung und weisen darauf hin, was der Benutzer beachten sollte.

Zum Beispiel, anstatt zu schreiben: „In diesem Tutorial wirst du lernen…“ beginne mit „In diesem Tutorial richten wir eine Online-Dokumentation mit Nuxt UI Pro und Directus CMS ein. Auf dem Weg werden wir Tailwind CSS verwenden und die Versionsverwaltung mit Git einrichten…“

Wir halten die Erzählung der Erwartungen aufrecht, indem wir Sätze wie: „Einige Momente nach dem Commit deiner Änderungen an Git wirst du die Ergebnisse auf deiner Website sehen.“

Zeige dem Benutzer Beispiele oder tatsächliche Ausgaben und verbessere die Beobachtungsfähigkeiten, indem du unterwegs darauf hinweist, was der Benutzer beachten sollte. Dies könnten zum Beispiel Änderungen in der Befehlszeile oder Reaktionen der Umgebung sein.

Tutorials können folgendermaßen strukturiert werden:

• Einleitung/Lernziele - Gibt an, was der Benutzer im Tutorial erreichen wird.
• Voraussetzungen - Listet erforderliches Wissen/Werkzeuge auf.
• Schritt-für-Schritt-Anweisungen - Bietet praktische Übungen und Aktivitäten.
• Zusammenfassung - Fasst die wichtigsten Lektionen und Erkenntnisse zusammen.
• Bewertung - Fragen oder Übungen zur Überprüfung des Verständnisses.
• Nächste Schritte - Verweist auf zusätzliche Ressourcen für weiteres Lernen.

Anleitungen

In diesem Abschnitt geht es darum, spezifische Ziele und Ergebnisse zu erreichen. Anleitungen richten sich an Benutzer, die aktiv arbeiten, bereits ein grundlegendes Verständnis für das Thema haben und mit den erforderlichen Werkzeugen vertraut sind. Da die Benutzer mit realen Problemen konfrontiert sind, wollen wir sie auf das Unerwartete vorbereiten. Oft finden sich Phrasen wie „Wenn dies…, dann das.“ um alternative Wege zur Erledigung bestimmter Aufgaben aufzuzeigen.

Anleitungen helfen sicherzustellen, dass die Schritte, die zum Erreichen des Ziels erforderlich sind, in der richtigen Reihenfolge ausgeführt werden und nichts ausgelassen wird. Wiederum wollen wir keine Erklärungen einfügen, da dies den Benutzer von der Arbeit ablenkt und die Lesbarkeit der Anleitung verringert. Es sollte auf Effizienz abzielen und daher nur so wenig wie möglich und so viel wie nötig Informationen für den Benutzer enthalten. Aus diesem Grund wollen wir den Benutzer bei der Arbeit auch nicht mit Einführungen zu Werkzeugen und Grundlagen belästigen, die bereits in Tutorials behandelt wurden.

Zum Beispiel, nach der Anleitung unserer Kunden durch ein Einführungstutorial zum Content-Management mit Directus CMS, bieten wir ihnen Schritt-für-Schritt-Anleitungen zur Implementierung verschiedener Funktionen wie Bildergalerien oder Veröffentlichungsautomatisierung.

Anleitungen können die folgenden Elemente enthalten:

• Voraussetzungen - Erforderliches Wissen oder Bedingungen zur Lösung des Problems.
• Einleitung - Falls erforderlich, eine detailliertere Beschreibung dessen, was die Anleitung abdeckt.
• Geordnete Schritte - Sequentielle Anweisungen zur Lösung des Problems, soweit möglich.
• Visuals - Diagramme und Illustrationen zur Unterstützung der Schritte.
• Beispiele - Konkrete Anwendungsfälle, die das Problem und die Lösung demonstrieren.
• Variationen - Wie sich die Schritte unter bestimmten Bedingungen unterscheiden können.
• Zusammenfassung - Zusammenfassung dessen, was erreicht wurde.
• Verwandte Links - Verweise auf andere verwandte Verfahren.

Referenzen

Ähnlich wie Erklärungen enthält Referenzmaterial theoretisches Wissen. Der Hauptunterschied besteht darin, dass es nicht verwendet wird, um ein bestimmtes Thema zu verstehen, sondern konsultiert wird, während der Benutzer arbeitet. Es folgt standardisierten Mustern und ist in einem neutralen und objektiven Ton verfasst. Oft enthält es Listen von Dingen oder Tabellen mit Informationen.

Zum Beispiel könnten Benutzer eine Liste von Tastenkombinationen konsultieren, während sie mit einer Software arbeiten, die ihnen noch nicht vertraut ist.

Referenzen können Elemente wie diese enthalten:

• Überblicke - Hochrangige Zusammenfassungen des Zwecks und der Fähigkeiten einer Komponente.
• Spezifikationen - Präzise technische Details zu Eingaben, Ausgaben, Konfigurationen usw.
• Optionen - Diagramme, die verschiedene Optionen oder Versionen vergleichen.
• Parameter - Listen, die alle verfügbaren Parameter und deren Verwendung

definieren.

• Codebeispiele - Schnipsel, die Implementierung und Verwendung demonstrieren.
• Visuals - Diagramme, die technische Konzepte und Beziehungen veranschaulichen.

Das ist unser Ansatz

Wie du in unserer eigenen Dokumentation sehen kannst, teilen wir „Erklärungen“ gerne in eine grundlegende Einführung, um alle auf denselben Stand zu bringen, und gehen dann, als letzten Punkt, in tiefgehende Erklärungen für alle, die alles wissen wollen.

So strukturieren wir unsere Dokumentationen:

• Einführung
• Tutorials
• Anleitungen
• Referenzen
• Tiefgehende Erklärungen

Natürlich benötigt nicht jede Dokumentation alle 5 Kapitel. Und manchmal möchtest du vielleicht zwei oder mehr der Kategorien zu einer zusammenfassen. Das Wichtigste ist, immer klar über die Bedürfnisse der Benutzer und das Ziel deiner Dokumentation zu sein.