Die Software Dokumentation
Eine gute Software-Dokumentation entscheidet nicht selten über den Erfolg oder Misserfolg einer Software. Egal ob es sich um eine Code-Dokumentation für Entwickler, um ein Handbuch für Administratoren oder um ein Benutzerhandbuch für Anwender handelt: Nur wenn die Software-Dokumentation präzise und einfach verständlich ist,.wird die Software auch gerne verwendet.
- Die Software Dokumentation
Wann eine Software-Dokumentation entsteht
Software-Dokumentation vor der Entwicklung
Die Dokumentation einer Software fängt bereits vor der Entwicklung der Software an. Denn bevor es an die Entwicklung geht, werden Ziele definiert, Ideen festgehalten, Konzepte geschrieben, UML-Diagramme erstellt oder sogar eine Infrastruktur konzipiert.
Ebenfalls vor der Entwicklung steht die Anforderungsbeschreibung. Dazu werden so gut wie immer Tickets erstellt, in denen einzelne Aufgaben oder Features beschrieben und Informationen gesammelt werden. Im agilen Umfeld werden beispielsweise Epics und Userstories genutzt, um die Ziele und Anforderungen an eine Software zu formulieren. All das ist bereits nutzbar für jede Arte von Dokumentation.
Software-Dokumentation während der Entwicklung
Während der Entwicklung wird der Quellcode für die Software oder das Feature geschrieben. Der Quellcode wird üblicherweise mit Kommentaren versehen, die einem bestimmten Muster folgen. Mit Hilfe dieser Kommentare können später automatisch oder auch halbautomatisch Code-Dokumentationen erzeugt werden.
Kommentare im Quellcode folgen meist einem bestimmten Muster und bleiben inhaltlich rudimentär. Üblich ist die Kommentierung von Klassen, Funktionen und Methoden in Form von DocBlocks. Nicht selten findet man jedoch auch Inline-Kommentare zu einzelnen Code-Abschnitten. In der Regel bestehen die DocBlocks aus einem kurzen Satz, den erlaubten Paramentern und dem Rückgabewert. Weiterführende und übergreifende Informationen, zum Beispiel wie eine Erweiterung für eine Software geschrieben werden kann oder welche Schnittstellen einer Software genutzt werden können, werden dagegen redaktionell in einer Entwickler-Dokumentation festgehalten. Für solche Entwickler-Dokumentationen werden häufig Wikis oder einfache Markdown-Dateien genutzt, aus denen dann HTML-Dokumentationen erzeugt werden.
Software-Dokumentation nach der Entwicklung
Nach der Entwicklung ist eine gute Anforderungsbeschreibung und eine gute Code-Dokumentation unerlässlich, denn aus diesen Dokumenten können dann Test-Szenarien abgeleitet werden, um die Software oder das Feature vor der Auslieferung zu überprüfen und die Qualität sicherzustellen.
Software-Dokumentation bei der Auslieferung
Von besonderer Bedeutung ist die Dokumentation bei der Auslieferung der Software, eines Releases oder eines Features, denn spätestens jetzt werden Informationen mit der Außenwelt geteilt. Wer im Vorfeld der Auslieferung bereits gute Dokumentations-Arbeit geleistet hat, ist natürlich im Vorteil. In dieser Phase geht es vor allem darum, die vorhandenen Informationen für die relevanten Zieltruppen aufzubereiten und in den verschiedenen Medien und Formaten zu veröffentlichen. Allen voran natürlich das Benutzerhandbuch, die öffentliche Entwickler-Dokumentation, ein Administrationshandbuch, genauso aber auch eine Pressemitteilung, ein Newsletter, ein Blog-Eintrag, Tutorials, Materialien für das Marketing, ein öffentliches Changelog oder auch die beliebten FAQs.
Software-Dokumentation während des Betriebs
In den seltensten Fällen denkt man bereits bei der Veröffentlichung einer Software an alle Informationen, die für die verschiedenen Zielgruppen relevant sind. Daher sollte die Dokumentation während des Beitriebs permanent nachgearbeitet werden. Hilfreich sind hier alle Rückkanäle für den Anwender. Das können Issues auf GitHub genauso sein wie Support-Anfragen, häufig wiederkehrende Anwenderfehler oder auch allgemeine Hinweise von Nutzern.
Arten der Software-Dokumentation
An einer Software-Dokumentation sind viele Menschen beteiligt. Die Entwickler, die Produkt Owner, die Tester, Redakteure und Mitarbeiter aus Marketing und Kommunikation. Es gibt jedoch nicht nur die eine Dokumentation, sondern verschiedene Dokumentationen für verschiedene Zielgruppen, die mit der Software interagieren.
- Interne Software-Dokumentation: Zielgruppe sind alle Mitarbeiter eines Software-Unternehmens. Die interne Software-Dokumentation soll die Entwicklung und die Wartung der Software erleichtern. Dabei gibt es verschiedene Formen der Dokumentation, neben der Code-Dokumentation beispielsweise die Prozessdokumentation, die Projektdokumentation, die Produktdokumentation, die Systemdokumentation, die Testdokumentation, die Dokumentation des Design-Systems oder auch Styleguides, die die Prinzipien für die Gestaltung von Oberflächen vorgeben. Die Dokumenationen sollten regelmäßig aktualisiert und leicht zugänglich gemacht werden, um eine effiziente und konsistente Arbeit zu ermöglichen.
- Code-Dokumentation: Die Code-Dokumentation richtet sich an interne und externe Software-Entwickler. Sie beinhaltet Kommentare im Quellcode, die die Funktionsweise von Klassen, Methoden und Algorithmen erklären. Sie sollte auch Informationen über wichtige Designentscheidungen, Ausnahmenbehandlung, Abhängigkeiten zwischen Code-Teilen und Beispiele für die Code-Nutzung enthalten. Ziel ist es, die Lesbarkeit und Wartbarkeit des Codes zu verbessern.
- Entwickler-Dokumentation: Die Entwickler-Dokumentation richtet sich an externe Entwickler, die eine Software nutzen und integrieren. Sie ist neben dem Benutzerhandbuch das Aushängeschild einer Software und beinhaltet üblicherweise Einführungen, Schritt-für-Schritt-Anleitungen und Code-Referenzen.
- API-Dokumentation: Die API-Dokumentation ist eine Spezial-Form der Entwickler-Dokumentation und richtet sich an (externe) Entwickler, die die API einer Software nutzen wollen. Die Dokumentation beinhaltet eine Referenz der API-Endpunkte, Anfrage- und Antwortformate, verfügbare Methoden, Parameter, Fehlercodes und Beispiele für Anfragen und Antworten. Ein interaktiver API-Explorer kann ebenfalls hilfreich sein.
- Administrationshandbuch: Das Administrationshandbuch richtet sich an IT-Administratoren, die für die Einrichtung, Konfiguration, Wartung und Sicherheit der Software verantwortlich sind. Es sollte detaillierte Anleitungen zur Installation, Konfigurationsanweisungen, Systemanforderungen, Netzwerkeinstellungen, Sicherheitsempfehlungen und Troubleshooting-Informationen enthalten.
- Benutzerhandbuch: Das Benutzerhandbuch einer Software ist für Endbenutzer konzipiert, um ihnen die Nutzung der Softwareoberfläche zu erleichtern. Es sollte eine schrittweise Anleitung für die grundlegenden Funktionen, Screenshots, FAQs, Tipps zur Fehlerbehebung und Kontaktinformationen für weiteren Support bieten. Es kann auch Videos und interaktive Tutorials enthalten, um das Lernen zu erleichtern.
Neben diesen klassischen Dokumentationen kann es noch weitere Informations-Materialien im Umfeld einer Software geben:
- Installationsanleitung: Speziell für die initiale Einrichtung der Software. Sie sollte Schritt-für-Schritt-Anweisungen für die Installation, Konfiguration von Software-Abhängigkeiten und erste Schritte nach der Installation umfassen.
- Release-Notizen und Changelogs: Wichtig für Benutzer und Administratoren, um über neue Funktionen, Bugfixes, Sicherheitsupdates und mögliche Kompatibilitätsprobleme in neuen Versionen der Software informiert zu sein.
- FAQs (Häufig gestellte Fragen): Eine Sammlung von häufig gestellten Fragen und Antworten, die sowohl für Endnutzer als auch für interne Teams nützlich sein kann, um schnell gängige Probleme und Lösungen zu finden.
- Troubleshooting-Leitfaden: Speziell für die schnelle Identifizierung und Behebung von häufigen Problemen und Fehlern, sowohl für Endnutzer als auch für Administratoren.
- Knowledge-Base: Die Wissensdatenbank oder Knowledge Base ist eine zentrale, organisierte Sammlung von Informationen, die typischerweise verwendet wird, um Fragen zu beantworten und Probleme zu lösen. Sie kann Artikel, FAQs (häufig gestellte Fragen), Handbücher, Leitfäden, Video-Tutorials und weitere Dokumentationsformen enthalten.
Formate und Medien
Bei der Software-Dokumentation kommen unterschiedliche Eingangsformate, Ausgabeformate und Medien-Formate zum Einsatz. Als Eingangsformat für Software-Dokumenationen spielt heutzutage vor allem Markdown eine große Rolle, da Markdown das übliche Eingangsformat der beliebten Static Site Generatoren ist. Außerdem ist Markdown auf vielen Online-Plattformen wie beispielsweise GitHub verbreitet. Markdown ist eine universelle Auszeichnungssprache, die in viele andere Formate transferiert werden kann, insbesondere in HTML. Andere Auszeichnungssprachen, die generell für Dokumentationen genutzt werden, sind ReStructuredText und LaTeX. In der technischen Dokumentation wird häufig mit XML-Formaten gearbeitet, insbesondere mit DITA und DocBook. Viele kleine Unternehmen nutzen für Software-Dokumentationen immer noch Microsoft Word oder Google Docs.
Bei den Ausgabeformaten von Software-Dokumentationen kommt es auf den Bereich an: Während Entwickler-Dokumentationen für Web-Software fast ausschließlich als HTML-Seiten angeboten werden, sind bei Anwenderdokumentationen PDF- und auch Print-Formate üblich, insbesondere wenn es um Software im Maschinen-Bereich, um Hardware oder um andere physische Produkte geht.
Die Verwendung von Medien in einer Software-Dokumentation variiert je nach Software-Typ und Zielgruppe. Neben Texten und Bildern sind Bewegtbilder animated Gifs, Screencasts und Video-Anleitungen gebräuchlich. Bei den Bildern kommen neben Screenshots auch die unterschiedlichsten Skizzen und Diagramme (z.B. UML) zum Einsatz. Im Zeitalter der KI ist absehbar, dass Chatbots und dialog-orientierte Formate auch im Bereich der Software-Dokumentation zunehmend an Bedeutung gewinnen werden.
Anforderungen und Normen
Für die Software-Dokumentation ist neben der Standard-Norm für technische Redakteure (82079) vor allem die Normenreihe 2651x relevant, insbesondere die Normen 26514 und 26515.
- IEC/IEEE 82079: "Erstellung von Nutzungsinformation (Gebrauchsanleitungen) für Produkte – Teil 1 Grundsätze und allgemeine Anforderungen"
- ISO/IEC/IEEE 26511: "Requirements for managers of information for users of systems, software, and services".
- ISO/IEC/IEEE 26512: "Requirements for acquirers and suppliers of information for users".
- ISO/IEC/IEEE 26512: "Requirements for testers and reviewers of information for users".
- ISO/IEC/IEEE 26514: "Systems and software engineering – Design and development of information for users".
- ISO/IEC/IEEE 26515: "Developing information for users in an agile environment".
Weitere Normen zur Produktion von Anleitungs-Videos (26516) und zur Entwicklung von Benutzerunterstützung in mobilen Anwendungen (26517) sind in Vorbereitung.
Organisationen und Ansprechpartner
- ISO (International Organization for Standardization), IEC (International Electrotechnical Commission) und IEEE (Institute of Electrical and Electronics Engineers): Diese Organisationen entwickeln internationale Normen, einschließlich vieler Standards für Software- und Systemdokumentation.
- tekom: Der größte Fach- und Berufsverband für Technische Kommunikation.
- Write The Docs: Eine globale Community von Menschen, die sich mit dem Thema Dokumentation befassen.