Softwaredokumentation, das unbekannte Wesen?

Mit zunehmender Digitalisierung steigt der Bedarf an Softwaredokumentation. Dieser Artikel bietet Einsteigern einen Überblick über die wesentlichen Merkmale von Softwaredokumentation. Was macht gute Softwaredokumentation aus und was müssen Technische Redakteure wissen, um sie zu erstellen?

Erfahren Sie mehr über unsere Services: Wir erstellen Ihre Softwaredokumentation.

Was ist Softwaredokumentation?

Stellen Sie sich Software als Fluss vor. Erfüllt die Software ein paar wenige Grundfunktionen, fließt der Fluß gleichmäßig in seinem Flussbett. Je mehr Abhängigkeiten, Daten und Funktionalitäten die Software hat, desto breiter und reißender wird er.

Stellen Sie sich jetzt auf der linken Flussseite einen Anwender vor. Ängstlich betrachtet er das reißende, gurgelnde Wasser. Er will auf die andere Seite, ist jedoch verzagt. Wie soll er den Fluss überqueren? Wenn’s doch nur eine Brücke gäbe!

Technische Redakteure sind die Brückenbauer. Sie schreiben Softwaredokumentation, die die Brücke schlägt zwischen dem Wissen, das die Anwender haben und dem Wissen, das sie benötigen, um die Software korrekt zu verwenden.

Ohne Bild und kürzer: Softwaredokumentation erklärt Endanwendern, Administratoren und Entwicklern, wie Software funktioniert und wie sie sie bedienen.

Arten von Softwaredokumentation

Wir unterscheiden vier Arten von Dokumentation rund um Software:  

• Benutzerdokumentation. Das ist die klassische Anwenderdokumentation, die mit Software ausgeliefert wird, ein Großteil davon heute elektronisch.  
• Entwicklerdokumentation. Diese Dokumentation ist für Softwareentwickler gedacht. Sie beschreibt Schnittstellen, Frameworks, SDKs, technische Standards und APIs. Entwicklerdokumentation enthält alle Informationen, die Entwickler benötigen, um ihre Programmieraufgaben zu lösen, z. B. Erweiterungen für eine Standardsoftware zu programmieren.
• Systemdokumentation. Hier handelt es sich um Betreiberdokumentation für ein IT-System. Die Systemdokumentation beschreibt, welche Server, Dienste und Programme installiert sind, wie sie zusammenspielen und welche Daten ausgetauscht werden. 
• Interne Projekt- und Prozessdokumentation. Diese Dokumentation hält internes Wissen fest, z.B. zu Prozessen, Anforderungen, Testfällen und Konzepten in einem Software-Entwicklungsprojekt. Für interne Dokumentation gelten die gleichen Anforderungen wie für die anderen Dokumentationsarten.

Wir konzentrieren uns in diesem Artikel auf Anwender- und Entwicklerdokumentation.

Welche Anforderungen soll Softwaredokumentation erfüllen?

Die Anforderungen an Softwaredokumentation unterscheiden sich nicht wesentlich von Anforderungen an andere Arten von Dokumentation:

1. Softwaredokumentation beantwortet die Fragen der Anwender und versetzt sie in die Lage, das Produkt korrekt zu benutzen.
2. Softwaredokumentation ist verständlich und hält sich kurz. Um bei der Brücke zu bleiben: Wir bauen keine gewundene oder lückenhafte Brücke, sondern eine, die direkt von einem Flussufer zum anderen führt, ohne Umwege und Stolpersteine.
3. Softwaredokumentation richtet sich nach den Bedürfnissen und Aufgaben der Anwender. Anwender wollen nicht erst eine lange Einleitung lesen, bis sie zu den für sie wichtigen Inhalten kommen. Sie wollen wichtige Informationen schnell finden und verstehen.
4. Softwaredokumentation wird meistens zusammen mit der Software ausgeliefert.
5. Softwaredokumentation muss rechtlichen Anforderungen genügen. Im Folgenden finden Sie eine Liste von wichtigen Normen, die für Softwaredokumentation gelten. Hier wollen wir nicht detailliert auf diese Normen eingehen. Aber wir empfehlen Ihnen, die Normen zu verwenden – nicht nur aus rechtlichen Gründen, sondern auch, weil sie viel wertvolles Wissen enthalten, das Sie für das Schreiben von guter Softwaredokumentation verwenden können.

• ISO/IEC 82079-1: „Erstellen von Gebrauchsanleitungen – Gliederung, Inhalt und Darstellung“
• ISO/IEC 26514: „Requirements for designers and developers of user documentation“
• ISO IEC IEEE 26511: „Anforderungen an Manager von Informationen für Benutzer von Systemen, Software und Services“
• ISO IEC IEEE 26512: „Anforderungen an Erwerber und Lieferanten von Informationen für Benutzer“
• ISO IEC IEEE 26513: „Anforderungen an Tester und Gutachter der Benutzerdokumentation“
• ISO IEC IEEE 26515: „Entwicklung von Benutzerdokumentation in einem agilen Umfeld“
• ISO 15289: Systems and software engineering - Content of life-cycle information items (documentation)

Wer schreibt Softwaredokumentation?  

Softwaredokumentation wird nicht immer von Technischen Redakteuren geschrieben.

• Entwickler: Viele Entwickler sind auch Brückenbauer und schreiben Softwaredokumentation. Das kann ein Vorteil sein, denn wer kennt sich besser aus mit der Software? Andererseits kann das viele Wissen der Entwickler auch zum Nachteil werden. Denn manchmal fällt es Entwicklern schwer, ihr umfangreiches Spezialwissen auf das Wissen herunterzubrechen, das die Anwender in einer bestimmten Situation benötigen.
• Qualifizierte Fachanwender: Auch qualifizierte Fachanwender mit Expertenwissen schreiben Dokumentation. Sie sind teilweise bereits in der Produktentwicklung oder im Produktmanagement eingebunden und kennen sich am besten mit der Bedienung der Software aus.
• Technische Redakteure: Ausgebildete Technische Redakteure sind darauf spezialisiert, anwenderorientiert zu schreiben. Sie testen die Software und machen sich mit ihren Funktionalitäten vertraut. Dadurch nehmen sie ganz automatisch die Sicht des Anwenders ein und wissen, welche Informationen die Anwender in welchen Situationen benötigen.

Erfahren Sie mehr über unsere Services: Wir erstellen Ihre Softwaredokumentation.

Für wen schreiben wir? Die Zielgruppenanalyse

Wir haben gesagt, dass Softwaredokumentation die Fragen der Anwender beantwortet. Deswegen müssen wir zunächst mehr über die Anwender erfahren und unsere Zielgruppen analysieren. Dabei erfahren wir:

• Wer sind die Anwender?
• Was wissen die Anwender?
• Welche Erwartungen haben die Anwender?
• Welche Aufgaben führen die Anwender aus?

Wer sind die Anwender?

In Softwaredokumentation treffen wir immer wieder auf drei typische Zielgruppen:

• Endanwender: Sie sind die Anwender der Software.
• Entwickler: Sie arbeiten in der Regel mit Software-Erweiterungen, APIs oder Plug-ins.
• Administratoren: Sie richten die Software ein, rollen sie aus, aktualisieren und warten sie.

Entsprechend der Zielgruppen gibt es für viele Software-Produkte die folgenden typischen Informationsprodukte:

• Anwenderdokumentation
• Anleitungen für Programmierer
• Administratordokumentation

Jede dieser Zielgruppen müssen wir separat analysieren. Das bedeutet, dass wir die Fragen in den folgenden Abschnitten für jede Zielgruppe einzeln beantworten müssen.

Was wissen Anwender?

Zunächst wollen wir herausfinden, was die Anwender wissen. Welche Kenntnisse bringen sie mit und welche Kenntnisse benötigen sie, um die Software zu verwenden?

Für diese Analyse eignet sich eine Matrix. Im folgenden Beispiel einer Logistiksoftware haben wir versucht herauszufinden, welche Kenntnisse die Leser einer Administrator-Dokumentation haben. Für jede Beobachtung ziehen wir eine Schlussfolgerung für die Gestaltung der Dokumentation.

Welche Erwartungen haben Anwender?

Die Erwartungen der Zielgruppe betreffen mehrere Bereiche:

Das habe ich immer schon so gemacht!

Stellen Sie sich Anwender vor, die bereits zehn Jahre lang mit einer Vorgängerversion der Software gearbeitet haben: „Das haben wir schon immer so gemacht!“, „Wo ist mein PDF?“, „Ich brauch keine Online-Hilfe!“

Die Gewohnheiten aus Vorgängerversionen können die Erwartungen der Anwender prägen. Vielleicht entscheiden Sie sich aber auch bewusst, mit alten Gewohnheiten zu brechen.

Visuelle Aufbereitung

Ob und wie viele Bilder, Videos oder andere visuelle Mittel wir verwenden, hängt auch stark von den Erwartungen und den Kenntnissen der Zielgruppe ab:

• Sind die Anwender eher textuell orientiert, kommt man mit weniger Bildern aus.
• Ein Administrator benötigt bei einer Beschreibung der Parameter ggf. keinen Screenshot.
• Ein Endanwender, der die Software noch nicht kennt, braucht stärkere visuelle Hilfsmittel wie Screenshots oder Video-Tutorials.

Zugriff auf die Hilfe

In den meisten Fällen stellen wir Softwaredokumentation als Online-Hilfe oder PDF zur Verfügung. Gedruckt wird kaum noch. Welches Format wir wählen, hängt u.a. auch wieder von den Erwartungen der Anwender ab.

Wollen die Anwender lieber ein PDF, weil sie es gewohnt sind, offline arbeiten wollen oder sich Seiten für unterwegs ausdrucken können?

Gibt es Anwender, die schon immer nur mit einer Online-Hilfe gearbeitet haben?

Ist die Zielgruppe an Dokumentation als PDF gewöhnt, dann könnten wir das PDF zusätzlich zur Online-Hilfe ausliefern. So decken wir die Wünsche und Erwartungen aller Anwender ab.

Informationsbedarf

Mittlerweile wissen wir, welche Kenntnisse die Anwender mitbringen, d. h. wir wissen, ob wir Fachbegriffe erklären müssen oder nicht. Nun sollten wir herausfinden, welche Informationen die Anwender benötigen. 

Ein gewisses Maß an Grundwissen sollten wir immer voraussetzen: Die meisten wissen, wie man ein Fenster schließt oder ein Menü öffnet. Diese Aufgaben müssen wir in der Dokumentation nicht beschreiben.

Standardvorgänge versus Spezialfälle: Einer unserer Kunden ist ein großes Hamburger Logistikunternehmen. Hier gibt es Standardanwendungsfälle, die jeder verantwortliche Mitarbeiter kennt und vermutlich selten in der Dokumentation nachschlägt: ein Angebot für das Verschiffen von Ladung nach Schanghai erstellen, Frachtraten und Zuschläge berechnen, Fracht überwachen und ausliefern. Doch was passiert, wenn das Schiff umgeleitet wird und sich die Zuschläge ändern, weil die Ladung plötzlich nicht mehr in Schanghai, sondern in Singapur gelöscht wird? Mit diesen Fällen kennen sich die Mitarbeiter nicht unbedingt aus. Das heißt, dass wir möglicherweise mehr Spezialfälle als Standardfälle beschreiben müssen.

Welche Aufgaben gibt es?

Softwaredokumentation, insbesondere Dokumentation für Endanwender, ist stark aufgabenbasiert. Deswegen finden wir im nächsten Schritt heraus, welche Aufgaben mit der Software ausgeführt werden. Dafür haben wir zwei Möglichkeiten: Wir sehen uns (1) den Produktlebenszyklus der Software an und (2) die Aufgaben, die innerhalb eines Geschäftsprozesses anfallen.

Produktlebenszyklus

Der Lebenszyklus einer Software besteht aus verschiedenen Abschnitten:

• Installation
• Konfiguration
• Betrieb
• Fehlerbehebung
• Anpassungen
• Aktualisierung
• Wartung
• Deinstallation

Diese Abschnitte können bereits die grobe Struktur für unsere Dokumentation vorgeben. In jedem Fall bieten sie die Themen, die wir in der Dokumentation abdecken müssen, wenn sie rechtssicher sein soll.

Aufgaben innerhalb von Geschäftsprozessen

Die zweite, ergänzende Möglichkeit, die Aufgaben der Zielgruppe kennenzulernen, ist die Analyse der Geschäftsprozesse. Kehren wir zum Logistiker zurück. Wir haben uns dort den Hauptgeschäftsprozess angesehen und einige der Aufgaben identifiziert, die erforderlich sind, um z. B. einen Container von Hamburg nach Schanghai zu verschiffen:

• Angebot erstellen
• Auftrag annehmen
• Frachtraten und Zuschläge kalkulieren
• Verschiffung überwachen
• Container liefern
• Zahlungseingang überprüfen
• Monatsabschluss erstellen

Diese Aufgaben repräsentieren die Themen in unserer Dokumentation. Kehren wir kurz zurück zum Lebenszyklus der Software, stellen wir auch fest, dass Schritte 1 – 7 höchstwahrscheinlich im Abschnitt „Betrieb“ enthalten sind.

Wer macht was?

Jetzt wissen wir, welche Aufgaben es gibt. Nun sehen wir uns an, wer die Aufgaben ausführt. Für diese Untersuchung eignet sich eine „Wer-macht-was-Matrix“.

Wieder betrachten wir die Aufgaben im Prozess „Container von Hamburg nach Schanghai verschiffen“. Wir haben vier Zielgruppen identifiziert: Operator, Subunternehmer, Buchhalter und Controller. Für jede Zielgruppe gibt es ein eigenes Informationsprodukt: Operator Manual, Subcontractor Manual, Accounting Manual und Controlling Manual. Markieren Sie in der Matrix, für welche Zielgruppen welche Aufgaben relevant sind.

Die Matrix hilft uns zu verstehen, welche Inhalte wir in welchem Informationsprodukt unterbringen.

Sind die Aufgaben klar voneinander getrennt und gibt es keine Überschneidung von Informationen zwischen den Informationsprodukten, erstellen wir unterschiedliche Inhalte, z. B. für das Operator Manual und das Controlling Manual. Oft sind aber mehrere Zielgruppen an einer Aufgabe beteiligt, z. B. wenn Operator und Subunternehmer die Verschiffung des Containers überwachen. In diesem Fall haben wir mehrere Möglichkeiten:

a) Wir entscheiden wir uns dafür, die Inhalte einmal zu erstellen und sie in den verschiedenen Informationsprodukten wiederzuverwenden.

b) Wir fassen Inhalte für mehrere Zielgruppen in einem Informationsprodukt zusammen und gruppieren die Themen nach Zielgruppen.

Wie verhalten sich Anwender?

Um anwendergerecht zu dokumentieren, müssen wir auch verstehen, wie die Anwender die Dokumentation nutzen. Menschen lernen und beschaffen sich Informationen auf unterschiedliche Weise. Nachfolgend stellen wir Ihnen drei Anwendertypen vor, die wir häufig antreffen:

• Losleger
• Nachschlager
• Lerner

Denken Sie aber nicht in Schubladen, wir können diese Anwendertypen nie klar voneinander trennen. Meistens treffen wir Mischformen an. Trotzdem hilft uns diese Unterscheidung, den Anwendern die Informationen zur Verfügung zu stellen, die für ihren Typ geeignet sind.

Losleger

Losleger fangen sofort an, ihre Arbeitsaufgabe in der Software zu lösen. Sie schauen nicht in die Dokumentation. Hilfe suchen sie nur, wenn es ein Problem gibt. So kann es bei unserer Logistikmitarbeiterin vorkommen, dass das Schiff, auf dem sie Container versendet hat, wegen eines Sturms nicht den Hafen von Schanghai anlaufen kann und stattdessen die Ladung in Singapur gelöscht wird. Frachtraten und Zuschläge ändern sich. Wie macht sie das in der Software?

• Diese Anwender brauchen Problemlösungen. Sie lesen Aufgabenbeschreibungen und FAQs. Am besten geeignet ist eine Online-Hilfe oder ein Web-Portal, mit denen sie in wenigen Sekunden die gesuchte Information finden. Dafür benötigt unsere Dokumentation eine gute Verschlagwortung und Volltextsuche.

Nachschlager

Diese Anwender lesen Aufgabenbeschreibungen, Anwendungsfälle oder Referenzthemen bei Bedarf und bevor sie in der Software einfach loslegen. Wenn der Administrator der Logistiksoftware beispielsweise Informationen über Parameter benötigt, öffnet er einen Dialog in der Software, drückt F1 und liest sich die Eigenschaften jedes einzelnen Parameters durch. 

• Für diese Anwender benötigen wir kontextsensitive Hilfe, die die Dialoge beschreibt.

Lerner

Das sind die Anwender, die lernen und verstehen wollen, wie die Software funktioniert und aufgebaut ist. Sie lesen Konzepte.

• Für die Lerner erstellen wir Konzepte, Hintergrundinformationen oder Architekturmodelle.

Alle Anwendertypen bedienen

Es gibt Anwender, die nur die Aufgabenbeschreibungen lesen. Andere lesen nur konzeptionelle Informationen und lesen dann nicht mehr die Aufgabenbeschreibungen. Sie haben das Gedankenmodell der Software im Kopf und können sich den Rest selbst erschließen. Unser Rat: Bedienen Sie alle Anwendertypen, denn in der Regel kommen sie auch alle vor.

Womit lesen die Anwender?

Mittlerweile lesen wir Dokumentation mit unterschiedlichen Medien: Desktops, Smartphones, Tablets oder auch, in Verbindung mit Augmented Reality, Smart Glasses.

Für unsere Dokumentation benötigen also mehrere Ausgabeformate. Erstellen wir die Dokumentation mit XML oder Markdown, verfügen wir bereits über formatneutrale Inhalte, die wir in verschiedenen Formaten veröffentlichen können.

Wie lesen die Anwender?

Wir sollten uns aber auch fragen, wie und wo die Anwender die Dokumentation lesen. Lesen sie zum Beispiel online oder offline?

Kennen Sie die Situation? Sie sitzen in der Bahn, arbeiten am Computer und versuchen, die Hilfe eines Microsoft-Produkts zu öffnen – häufig ohne Erfolg. Eine Offline-Hilfe gibt es nicht. Das ist für Microsoft-Produkt möglich, aber in anderen Anwendungssituationen müssen wir Hilfe auch offline zur Verfügung stellen. Beispiel: Hilfe für Geräte, die nicht mit dem Internet verbunden sein dürfen, wie z.B. Röntgengeräte.

Wir haben gute Erfahrungen mit webbasierten Hilfen gemacht, die auch offline funktionieren. Sie verfügen über eine Volltextsuche und gute Indexierung, das heißt, die Anwender finden Inhalte auch, wenn sie offline sind.

Wie suchen die Anwender?

Wichtig ist auch, dass wir herausfinden, wie die Anwender in der Hilfe suchen: Möchten sie mit einem Chatbot kommunizieren, geben sie ihre Frage ins Suchfeld ein oder verwenden sie ganz klassisch das Inhaltsverzeichnis? Diese Fragen beantwortet ein Usability-Test. Viele Unternehmen scheuen vor den Kosten dieser Tests zurück. Langfristig sparen sie jedoch Geld, da sie die Bedienerfreundlichkeit des Produkts verbessern sowie Supportkosten und Dokumentationsaufwände verringern. Auch Technische Redakteure können Usability-Tests durchführen und die Bedienerfreundlichkeit des Produkts testen, gerade in kleineren Unternehmen, in denen es kein gesondertes Budget dafür gibt .* 

Im nächsten Teil: Topic-basiertes Schreiben und Tools für Dokumentation und Auslieferung. 

* Quellen

• https://www.tekom.de/uploads/media/Usability_fuer_Techn_Redakteure.pdf
• https://tagungen.tekom.de/h19/arena/arena-ux/