Inhaltsverzeichnis

Gute Softwaredokumentation ist der Schlüssel zu erfolgreicher Softwareentwicklung und -nutzung. Sie hilft Entwickler:innen, Endanwender:innen und Wartungsteams, die Software effizient zu verstehen und zu nutzen.

Dabei gibt es unterschiedliche Arten von Dokumentation, die verschiedenen Zwecken dienen. Im Wesentlichen unterscheiden wir zwischen interner und externer Dokumentation. Beide haben ihre eigenen Zielgruppen, Inhalte und Ziele. Bringen wir uns erstmal auf einen gemeinsamen Nenner: In diesem Abschnitt erläutere ich den Unterschied zwischen interner und externer Dokumentation einer Software.

Interne Dokumentation richtet sich an die Entwickler:innen und das technische Team, das die Software entwickelt und wartet. Sie umfasst detaillierte technische Informationen, die für das Verständnis, die Wartung und die Weiterentwicklung der Software notwendig sind. Hier sind einige Merkmale und Bestandteile der internen Dokumentation:

Merkmale

  1. Zielgruppe: Entwickler:innen, Systemarchitekt:innen, QA-Tester:innen und andere technische Teammitglieder.

  2. Inhalt: Technische Details, die für das Verständnis des Codes und der Architektur notwendig sind.

  3. Detailgrad: Sehr detailliert und technisch, um spezifische Informationen über die Implementierung zu liefern.

  4. Zweck: Unterstützung der Wartung, Fehlerbehebung, Weiterentwicklung und des Onboardings neuer Teammitglieder.

Bestandteile

  • Code-Kommentare: Beschreibungen innerhalb des Quellcodes, die erklären, was bestimmte Codeabschnitte tun.

  • Technische Spezifikationen: Dokumente, die die Architektur, die Module und die Interaktionen zwischen den Komponenten beschreiben.

  • API-Dokumentation: Detaillierte Beschreibungen der Schnittstellen und Endpunkte der Software.

  • Entwicklerhandbuch: Anleitungen für die Entwicklungsumgebung, Build-Prozesse und andere Entwicklungspraktiken.

  • Fehlerprotokolle und Wartungshandbücher: Dokumentation zur Fehlerbehebung und Wartung der Software.

Externe Dokumentation richtet sich an die Endanwender:innen und andere externe Stakeholder, wie Kund:innen oder Partnerfirmen. Sie soll die Nutzung der Software erleichtern und sicherstellen, dass die Anwender:innen die Funktionen der Software verstehen und effektiv nutzen können. Hier sind einige Merkmale und Bestandteile der externen Dokumentation:

Merkmale

  1. Zielgruppe: Endanwender:innen, Kund:innen, Geschäftspartner:innen, Administrator:innen

  2. Inhalt: Benutzerfreundliche Erklärungen und Anleitungen zur Nutzung der Software.

  3. Detailgrad: Weniger technisch, dafür benutzerfreundlich und leicht verständlich.

  4. Zweck: Unterstützung der Benutzer:innen bei der Nutzung der Software, Beantwortung von Fragen und Lösung von Problemen.

Bestandteile

  • Schnellstartanleitungen: Kurze Anleitungen für die ersten Schritte mit der Software.

  • FAQ: Häufig gestellte Fragen und ihre Antworten.

  • Tutorials und Schulungsvideos: Visuelle und interaktive Hilfen, um die Nutzung der Software zu erklären.

  • Benutzerhandbuch: Ausführliche Anleitungen zur Nutzung der Software, oft mit Screenshots und Schritt-für-Schritt-Anweisungen.

  • Release Notes: Informationen über neue Funktionen, Verbesserungen und Fehlerbehebungen in neuen Versionen der Software.

Beide Arten der Dokumentation sind essenziell für den Erfolg einer Software und sollten sorgfältig erstellt und gepflegt werden, um die Bedürfnisse aller Nutzer:innen zu erfüllen.

Die Arten von Softwaredokumentation sind also klar. Doch was macht eine gute Softwaredokumentation aus? In diesem Blogbeitrag erfährst du alles über die Struktur, den Inhalt und erhältst Beispiele, um das 1×1 guter Softwaredokumentation zu verstehen.

Struktur einer guten Softwaredokumentation

Eine gut strukturierte Softwaredokumentation folgt keiner starren, chronologischen Abfolge, sondern einer flexiblen und verknüpfbaren Hierarchie. Hier sind die wesentlichen Bestandteile:

  1. Einführung
    Zweck: Beschreibt den Zweck der Software und warum sie entwickelt wurde.
    Zielgruppe: Identifiziert, für wen die Dokumentation gedacht ist (Entwickler:innen, Endanwender:innen, Administrator:innen).
  2. Installation
    Systemvoraussetzungen: Betriebssysteme, Hardware-Anforderungen, notwendige Zusatzsoftware.
    Installationsanleitung: Schritt-für-Schritt-Anleitung zur Installation der Software.
  3. Schnellstart
    Erste Schritte: Grundlegende Anweisungen, um die Software zum Laufen zu bringen.
    Beispielprojekte: Beispieldateien oder -projekte, die dir den Einstieg erleichtern.
  4. Nutzung
    Benutzeroberfläche: Beschreibung der UI und ihrer Elemente.
    Häufige Aufgaben: Anleitung zu häufig durchgeführten Aufgaben.
  5. Fehlerbehebung
    FAQ: Häufig gestellte Fragen und ihre Antworten.
    Problemlösungen: Anleitungen zur Behebung häufiger Probleme.
  6. Anhang
    Glossar: Definition von Fachbegriffen.
    Literaturhinweise: Weiterführende Ressourcen und Referenzen.

Inhalt einer guten Softwaredokumentation

Der Inhalt sollte klar, präzise und verständlich sein. Folgende Punkte solltest du berücksichtigen:

  1. Klarheit und Präzision
    Vermeide Jargon und komplizierte Sprache.
    Benutze kurze und prägnante Sätze.
  2. Visuelle Hilfsmittel
    Screenshots, Diagramme und Videos, um komplexe Informationen zu veranschaulichen.
    Tabellen und Listen, um Informationen strukturiert darzustellen.
    Falls du deine Zielgruppen mehrsprachig bedienst, ist vor allem bei visuellen Hilfsmitteln die sprachneutrale Darstellung die größte Herausforderung.
    Sprachabhängige visuelle Hilfsmittel „veralten“ sehr schnell und steigern den Pflegeaufwand – Setze daher z.B. auf SUI-Grafiken oder sogenannte Callout-Grafiken, um derartige Aufwände zu minimieren.
  3. Beispiele und Anwendungsfälle
    Praxisnahe Beispiele, die reale Szenarien abdecken.
    Code-Snippets mit Erläuterungen, die z.B. den Aufbau bestimmter Abfrageparameter erläutern.
  4. Aktualität
    Regelmäßige Updates der Dokumentation, um sie auf dem neuesten Stand zu halten.
    Richte den Update-Zyklus deiner Dokumentation am Entwicklungszyklus deiner Software aus.
    Plane Arbeitspakete für die Softwaredokumentation ebenfalls in deine Sprints ein, blocke dafür Kapazitäten.
    Versionshinweise, um Änderungen und Neuerungen nachvollziehbar zu machen.
  5. Nutzerfreundlichkeit
    Nutze die Macht guter Oberflächentexte (UX-Writing), um den Griff zur externen Dokumentation deiner Software zu minimieren.
    Auffindbarkeit deiner Informationen ist der Schlüssel – setze auf moderne Suchalgorithmen und zentralisierte Informationsbereitstellung.

Komplexität der Hierarchie in der Softwaredokumentation

Traditionell denken viele bei Dokumentation an ein Buchformat: eine Abfolge von Kapiteln, die linear gelesen werden. Diese Herangehensweise ist jedoch für Softwaredokumentation oft nicht ideal. Stattdessen ist es sinnvoller, in verknüpfbaren Themen oder Topics zu denken. Hier einige Gründe dafür:

  1. Verschiedene Nutzer, verschiedene Bedürfnisse
    Entwickler:innen benötigen andere Informationen als Endanwender:innen oder Administrator:innen. Durch verknüpfbare Themen können sie direkt zu den relevanten Informationen springen, ohne sich durch unnötige Abschnitte arbeiten zu müssen.

  2. Modularität und Wiederverwendbarkeit
    Einzelne Dokumentationsabschnitte sollten als eigenständige Module gestaltet werden, die bei Bedarf verknüpft oder aktualisiert werden können. Dies erleichtert nicht nur die Pflege der Dokumentation, sondern auch die Anpassung an unterschiedliche Versionen der Software.

  3. Nicht-lineare Navigation
    Oftmals benötigen Nutzer:innen nicht die gesamte Dokumentation, sondern nur spezifische Informationen. Durch Hyperlinks und Querverweise innerhalb der Dokumentation können sie schnell zu den benötigten Informationen navigieren.

  4. Flexibilität bei Updates
    Eine modulare Dokumentation kann leichter aktualisiert werden. Wenn sich eine Funktion ändert, muss nur der entsprechende Abschnitt angepasst werden, ohne dass dies Auswirkungen auf andere Teile der Dokumentation hat.

Beispiele guter Softwaredokumentation

Um die Theorie in die Praxis umzusetzen, schauen wir uns einige Beispiele an moderne Informationskonzepte für die Softwaredokumentation an:

      1. Schaffe einen zentralen Einstiegspunkt in dein Hilfe-Portal. Dort finden Nutzer alles, was sie an Information zu deinem Produkt benötigen.
        Verweise zur Dokumentation, Links zur Community, Release-Notes, Weiterbildungsinhalte und Co.

        Screenshot: STYRZ – Miro Hilfe-Portal – Zentraler Zugang zu Nutzerinformationen
      2. UX-Writing im Produkt: Microcopy oder auch GUI-Texte genannt, sorgen dafür, dass wichtige Inhalte, die die User-Journey unterstützen, direkt im Produkt als Platzhalter, Label-Texte oder Tooltips platziert werden. Sie ermöglichen es, den Nutzern den Blick in eine „nebenstehende“ Softwaredokumentation zu ersparen – Sie helfen also während des Vorgangs. Durch kleine Textschnipsel überbrückt man so Wartezeiten, vermeidet Fehlbedienungen und erspart den Blick in das Benutzerhandbuch.

        Sreenshot: STYRZ – Tool Zapier – Verbindung anlegen zwischen Gravity-Forms und Zapier.

      3. Moderne, weborientierte und flexible Navigationsstrukturen und standardisierte Inhaltsstrukturen in der Online-Hilfe ermöglichen viele Vorteile im Umgang mit den Online-Hilfen so zum Beispiel:

        a. Haupt- und Topic-Navigation für bessere Zugänglichkeit
        b. Konsistente Strukturen mit Wiedererkennungswert (Wo steht die Handlung, wo der Screencast?)
        c. Interaktive Screencasts für bessere Refernzbildung
        d. Kontextsensitive Querverweis
        e. Vollindexierte Suche für bessere Auffindbarkeit

        Screenshot: STYRZ – Mockup einer topicorientierten Online-Hilfe mit vielfältigen Navigationsstrukturen.

      4. Interaktive Demos im Produkt ermöglichen einen einfachen und schnellen Einstieg in neue Produkte. In den meisten Produkten, arbeiten Nutzer heutzutage mit Login-Daten. D.h. Softwarehersteller wissen i.d.R. sehr genau, wer die Person ist, die das Produkt aktuell bedient. Nutze dieses Potential, um die Person beim Besuch “neuer” Bereiche, aktiv zu unterstützen.

        Screenshot: STYRZ – Interaktive Demo in Hubspot zum Umgang mit dem Import und dem Filtern von Daten.

      5. Sammle Daten und Erkenntnisse über das Nutzungsverhalten im Umgang mit deinen Inhalten. Das ermöglicht dir, noch gezielter die Inhalte an den Bedarf deiner Zielgruppe(n) auszurichten, Content-Leichen zu eliminieren und die Qualität deiner Inhalte aufrecht zu erhalten.

        Screenshot: STYRZ – Analyseplattform im Content-Delivery-Portal eines STYRZ-Kunden.
      6. Ermögliche deinen Nutzern, Favoriten deiner Informationsprodukte zu speichern und bei Bedarf durch eigene Inhalte zu ergänzen. Das hat gleich mehrere Vorteile. Nutzer bauen ihre ganz eigene “perfekte” Anleitung und andererseits profitiert auch dein Unternehmen davon, den Bedarf zu erkennen und Tipps, Tricks und Kniffe auch mit anderen Kunden zu teilen.

        Screenshot: STYRZ – Personal-Books in einem Content-Delivery-Portal eines STYRZ-Kunden.

Fazit

Gute Softwaredokumentation ist essenziell für den Erfolg eines Softwareprojekts – im Problemfall ist der Nutzer bzw. die Nutzerin extra kritisch. Eine klare Struktur, präziser und verständlicher Inhalt sowie praxisnahe Beispiele sind die Grundpfeiler einer erfolgreichen Dokumentation. Durch eine flexible, verknüpfbare Hierarchie und regelmäßige Aktualisierungen bleibt die Dokumentation relevant und benutzerfreundlich. Nutze die genannten Beispiele als Inspiration, um deine eigene Softwaredokumentation zu verbessern und sicherzustellen, dass sie den Bedürfnissen deiner Nutzerschaft entspricht.

Wir haben da noch was für dich:

Du willst ein echter Softwaredoku-Profi werden? Wir haben einen Whitepaper für dich erstellt, der dir viele Tipps und Tricks zum Thema Softwaredoku an die Hand gibt – und das völlig kostenlos! Einfach hier herunterladen: