Was gehört in eine Softwaredokumentation?

Arten und Tipps für erfolgreiche Softwaredoku

Eine Software kommt nicht ohne die begleitende Softwaredokumentation aus. Entwickler, Benutzer und Support-Teams greifen darauf zurück, um die Software zu pflegen, vollumfänglich zu nutzen oder um Probleme und Fehler zu beheben. Wir haben uns angeschaut, welche Arten von Softwaredokumentation es gibt und was unbedingt in eine gute Softwaredoku gehört.

Was ist Softwaredokumentation? Nutzen und Zweck

Mit dem Begriff Softwaredokumentation bezeichnet man Informationen, Anleitungen und Begleitdokumentationen für eine Softwareanwendung oder ein Softwareprodukt. Softwaredokumentation kann sich sowohl an Nutzer als auch Entwickler und Tester von Softwareprodukten richten und soll die Leser dazu in die Lage versetzen, die Software vollumfänglich nutzen zu können einschließlich Installation und Wartung.

Die Softwaredokumentation ist eine spezielle Form der Technischen Dokumentation und spielt eine zentrale Rolle bei der Qualitätssicherung von Softwareprodukten. Softwaredokumentation dient der besseren Kommunikation zwischen Entwicklern und Endnutzern oder anderen Interessengruppen und trägt so zum nachhaltigen Erfolg eines Softwareproduktes bei.

Gibt es verschiedene Arten von Softwaredokumentation?

Je nach Zielgruppe und Inhalt unterscheidet man verschiedene Arten von Softwaredokumentation, wobei vor allem zwei Arten eine Rolle spielen:

Benutzerdokumentation

Richtet sich die Softwaredokumentation an Endnutzer, bezeichnet man sie auch als Benutzerdokumentation. Dabei kann es sich um Benutzerhandbücher, Anleitungen, Tutorials etc. handeln. Benutzerdokumentation erklärt die Verwendung der Software und die Ausführung von bestimmten Aufgaben für die Endnutzer.

Entwicklerdokumentation

Richtet sich die Softwaredokumentation an Entwickler und Softwareingenieure, bezeichnet man sie als Entwicklerdokumentation. Sie enthält Informationen zum Aufbau der Software, ihrer Architektur, dem Quellcode und APIs (Application Programming Interfaces). Entwicklerdokumentation ist ein wichtiger Baustein für das professionelle Entwickeln, Warten und Erweitern von Software.

Weitere Unterscheidungsmöglichkeiten von Softwaredokumentation sind u. a.:

Installationsdokumentation

Die Installationsdokumentation erklärt, wie die Software installiert und eingerichtet wird und welche Systemanforderungen nötig sind.

Testdokumentation

Die Testdokumentation enthält Informationen über die Testverfahren und Testergebnisse, die zur Entwicklung und Qualitätssicherung der Software durchgeführt wurden.

Systemdokumentation

Die Systemdokumentation hilft Systemadministratoren und IT-Experten, die Software in die entsprechende Softwareumgebung zu integrieren. Sie enthält technische Details zur Software und ihren Abhängigkeiten.

Wartungsdokumentation

Die Wartungsdokumentation versammelt Informationen zur Fehlerbehebung und Pflege der Software. Sie kann darüber hinaus auch Fehlerprotokolle, Aktualisierungshinweise und Tipps zur Leistungsverbesserung der Software enthalten.

Was gehört in eine Softwaredokumentation (Benutzerdokumentation)?

Erstellen Sie eine Softwaredokumentation, die sich als Benutzerdokumentation an Ihre Endnutzer richtet, sollten Sie den gesamten Produktzyklus der Software darin abdecken: von der Installation über die Konfiguration und Benutzung bis hin zur Fehlerbehebung, Anpassung / Aktualisierung und schließlich Deinstallation.

Die Benutzung wird wahrscheinlich den größtem Raum einnehmen. Erleichtern Sie den Gebrauch Ihrer Software, indem Sie den Nutzern die typischen Anwendungen erklären und mit Schritt-für-Schritt-Anleitungen und Handlungsanweisungen erläutern, was zu tun ist.

Tipps zum Erstellen von Softwaredokumentation

1. Zielgruppe: An wen richtet sich Ihre Softwaredokumentation? Möchten Sie die Endnutzer der Software erreichen? Oder wird Ihre Dokumentation von IT-Experten, Softwareentwicklern oder Systemadministratoren genutzt? Die Zielgruppe ist entscheidend dafür, wie Sie Ihre Softwaredokumentation aufbauen, welches Wissen Sie voraussetzen können und welche Fachbegriffe Sie nutzen können.
2. Problemlösung: Welche Aufgaben und Probleme möchte Ihre Zielgruppe lösen? Je besser Sie die Bedürfnisse und Absichten Ihrer Zielgruppe kennen, desto besser können Sie die Inhalte Ihrer Softwaredoku danach ausrichten.
3. Stil: Eine Dokumentation sollte so einfach wie möglich formuliert werden. Nutzen Sie genau so viel Text wie nötig. Verzichten Sie auf Füllwörter oder Ausschmückungen. Verwenden Sie stattdessen klare und eindeutige Anweisungen, keine vagen Beschreibungen, die offen für Interpretationen sind.
4. Visualisierungen: Veranschaulichen Sie Abläufe und auszuführende Schritte, wo immer es möglich ist. Ihre Leser werden es Ihnen danken. Visualisierungen verdeutlichen präzise, wo was ausgeführt werden muss. Ihre Leser müssen sich nicht durch lange Erläuterungen und Beschreibungen lesen, sondern sehen auf einen Blick, was Sie machen müssen. Zur Visualisierung von Softwaredokumentation haben Sie verschiedene Optionen:
5. Screenshots vom Bildschirm bilden eindeutig den Ist-Zustand der Software ab und helfen den Nutzern bei der Orientierung. Sparen Sie sich lange Beschreibungen und zeigen Sie stattdessen, was der Nutzer auf seinem Bildschirm sieht. Ergänzen Sie die Screenshots um Auszeichnungen wie Aufzählungen, Hinweistexte oder Markierungen, um das Bildmaterial mit weiteren hilfreichen Informationen anzureichern.

• Vereinfachte Nutzungsgrafiken (Simplified User Interface Graphics) liefern eine vereinfachte Darstellung einer Softwareoberfläche. Sie lenken den Blick auf die wichtigen Informationen und blenden unwesentliche Details aus. Diese SUI-Grafiken können Sie mit wenig Aufwand mit dem Bildschirmrekorder und Editor von Snagit erstellen. Ein weiterer Vorteil: Software wird regelmäßig geupdated und Details können sich ändern. Mit vereinfachten SUI-Grafiken müssen Sie nicht bei jedem Update Ihr Bildmaterial anpassen.
• Screencasts, also Videoaufzeichnungen vom Computerbildschirm, eignen sich ideal, um Arbeiten wie die Nutzung einer Software zu beschreiben oder Abläufe zu demonstrieren.

Weitere Tipps zum Erstellen Ihrer Softwaredokumentation:

1. Aktualität: Eine Softwaredokumentation ist nur hilfreich, wenn sie aktuell ist. Achten Sie darauf, bei Änderungen oder Aktualisierungen der Software auch die dazugehörige Dokumentation zu aktualisieren.
2. Logische Gliederung: Die Gliederung hilft Ihren Nutzern bei der Orientierung. Mit Titeln und Untertiteln sind relevante Themen schnell zu identifizieren. Wählen Sie deshalb aussagekräftige, konkrete Überschriften, die jeweils ein eng gefasstes Thema behandeln.
3. Zeitgemäßes Format: Bieten Sie Ihre Softwaredokumentation z. B. als Webportal oder Online-Hilfe an. Auch ein PDF zum Download ist möglich. Das gedruckte Handbuch ist veraltet.
4. Suchfunktion: Digitale Softwaredokumentation bietet einen großen Vorteil gegenüber gedruckten Handbüchern: die Möglichkeit, eine Suchfunktion einzubauen. Wir sind es gewohnt, Fragen und Stichwörter in ein Suchfeld einzugeben und mit einem Klick die gewünschten Antworten zu finden.

Sie sehen: Eine gut durchdachte und gestaltete Softwaredokumentation bietet viele Vorteile für die Nutzer Ihrer Software und trägt entscheidend zum nachhaltigen und langfristigen Erfolg Ihres Produktes bei.