Wie Sie gute Software-Dokumentation schreiben bzw. erstellen

Was ist eine Software-Dokumentation?

Es handelt sich um geschriebenen Text oder Illustrationen, die Computersoftware begleiten oder in den Quellcode eingebettet sind. Diese Technische Dokumentation liefert Informationen über die Verwendung eines Softwareprogramms, erklärt den Zweck der verschiedenen Komponenten und gibt einen Überblick über die Möglichkeiten des Programms.

Im Detail erklärt sie für diverse Interessensgruppen

• Funktionsweise,
• Ergebnisse und Prozesse,
• Bedienung,
• technische Voraussetzungen,

und differenziert dabei auch noch gemäß den jeweiligen Tätigkeiten.

Welche Arten von Software-Dokumentation gibt es?

Es gibt viele Arten von Software-Dokumentation, von der Übersicht über ein System bis hin zu detaillierten Spezifikationen einzelner Komponenten. Eine Grundunterscheidung basiert zunächst darauf, an wen sich die Dokumentation richtet: für den internen Gebrauch oder an Endanwender. Beide Fälle haben andere Anforderungen.

Interne Software-Dokumentation

Hierbei handelt es sich um eine Art von Dokumentation, die von den Entwicklern einer Software-Anwendung erstellt wird. Es gibt unter anderem folgende interne Dokumentationen:

• Entwicklerdokumentation
• Datendokumentation
• API-Dokumentation
• Installationsdokumentation
• Testdokumentation
• Projektdokumente
• Systemdokumentation

Die Entwicklerdokumentation soll anderen Programmierern helfen, die in Zukunft an dem Code arbeiten müssen. Diese Dokumentation kann Informationen über die Architektur der Anwendung, die Codestruktur und die Verwendung der verschiedenen Funktionen der Software enthalten. 

Die Datendokumentation soll helfen die vom Produkt benötigten oder erzeugen Daten zu verstehen, einzuordnen und mit ihnen zu arbeiten.

Die Installationsdokumentation beschreibt hingegen, vor allem bei komplexeren Systemen, wie und in welcher Reihenfolge Systemkomponenten installiert und eingerichtet werden müssen, damit die Gesamtfunktion gewährleistet ist.

Die Testdokumentation versucht die Tests zu beschreiben, die nötig sind, um die korrekte Funktion des Produkts zu überprüfen.

Projektdokumente sind vor allem für die Planung und Organisation der Softwareentwicklung gedacht, etwa wenn es um geplante Zielsetzungen, genutzte Tools oder Herangehensweisen geht.

Eine Systemdokumentation beschreibt ein komplexeres System einschließlich aller ihrer Komponenten, ihrer Funktionen und wie diese zusammenwirken.

Externe Software-Dokumentation

Externe Software-Dokumentation bezieht sich auf jene Dokumentation, die nicht Teil des Quellcodes eines Softwareprogramms ist. Dazu gehört alles, was für Personen bestimmt ist, die nicht zu den Entwicklern der Software gehören. Externe Dokumentation kann zwar sehr hilfreich sein, um zu verstehen, wie ein Programm zu verwenden und zu konfigurieren ist, sie kann aber auch eine Quelle der Verwirrung und Frustration sein, wenn sie nicht sinnvoll redaktionell aufbereitet, verständlich geschrieben oder nachvollziehbar strukturiert ist.

Beispiele für externe Software-Dokumentation sind unter anderem:

• Benutzerdokumentation / Benutzerhandbuch / Anwenderdokumentation (als pdf oder gedruckt)
• Online-Hilfe / Kontextsensitive Hilfe
• Leitfäden und Tutorials
• API-Dokumentation für Drittanbieter

Welche Anforderungen an Software-Dokumentation müssen erfüllt werden?

Allgemeine Anforderungen

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

1. Die Fragen der Endnutzer werden beantwortet und versetzt sie in die Lage, das Produkt korrekt zu benutzen.
2. Die Dokumentation ist verständlich und hält sich kurz.
3. Sie richtet sich nach den Bedürfnissen und Aufgaben der Anwender.
4. Die Auslieferung erfolgt meistens zusammen mit der Software.
5. Auch die Dokumentation muss rechtlichen Anforderungen genügen.

Normen

Für Softwarelösungen gibt es verschiedene Möglichkeiten, die Benutzerinformation (Benutzerhandbuch) passend zu erstellen. Damit ist nicht "nach gut Dünken" gemeint, sondern dass das Vorgehen und die Umsetzung sich an aktuell gebräuchlichen Methoden, wie z. B. dem Stand der Technik, orientieren.

Einerseits kann man sich an der DIN EN 82079-1 orientieren, die als Norm vor allem den Fokus auf Informationsvermittlung für jegliche Produktarten legt und generell relevant ist, wenn eine Dokumentation professionell erstellt werden soll.

Im Bereich Software lässt sich andererseits auch die Normenreihe ISO IEC IEEE 2651x mit Bezug auf Nutzerinformationen heranziehen, die in den einzelnen Normteilen die jeweiligen Kontaktgruppen der Benutzerinformation (vom Manager, Einkäufer und Lieferanten, Tester und Gutachter, Designer und Entwickler) und die agile Vorgehensweise anspricht.

Wer schreibt Software-Dokumentation?

Entwickler

Viele Entwickler erarbeiten die Software-Dokumentation selbst – mal mehr, mal weniger. Wer die Programmierung durchgeführt hat, weiß genauestens wie die Software funktioniert. Dies kann aber leider auch dazu führen, dass die Erklärung den technischen Horizont der Anwender weit überschreitet. Beim Erstellen können dadurch technische Details vorkommen, die eher verwirren als helfen. Denn um eine Software zu verwenden, muss der Benutzer die Feinheiten der inneren Funktionsweise meist nicht kennen.

Fachanwender

Dokumentationen können auch durch qualifizierte Fachanwender geschrieben werden. Da jene regelmäßig mit der Software arbeiten, wissen sie in der Regel welche Informationen andere Anwender benötigen. Allerdings sind solche Nutzer eher ein Glücksfall und Softwareentwickler sollten sich nicht darauf verlassen, dass Benutzerinformation auf diese Weise entsteht.

Technische Redakteure

Ausgebildete Mitglieder einer technischen Redaktion sind darauf spezialisiert dem Anwender der Software eine verständliche Anleitung zu geben, die einfach zu lesen ist. In der Regel machen sich technische Autoren mit der Anwendung und testen die verschiedenen Funktionen. So nehmen sie automatisch den Blick des unerfahrenen Benutzers ein und sehen welche Art von Information für diejenigen, die eine Dokumentation lesen, relevant ist.

Wie dokumentiert man Software?

Was gehört in eine Software-Dokumentation?

Sie enthält in der Regel eine Beschreibung der Software, eine Anleitung zu ihrer Verwendung und alle relevanten Informationen für Entwickler oder Endbenutzer. Ein gelungene Software-Dokumentation für Endnutzer sollte Informationen zu folgenden Punkten bezüglich des Produktlebenszyklus beinhalten:

• Installation: Wie wird das Programm auf einem Rechner installiert und welche Voraussetzungen gibt es hierfür?
• Konfiguration: Wie muss die Software eingestellt werden, damit sie den Anforderungen des Benutzers genügt?
• Benutzung: Welche Möglichkeiten bietet das Produkt und wie werden diese verwendet?
• Fehlerbehebung: Mit welchen Fehlern ist zu rechnen und wie können diese behoben werden?
• Anpassungsmöglichkeiten: Welche weiteren Optionen existieren, um die Funktionalität der Software zu erweitern z. B. durch Add-Ons?
• Aktualisieren / Updates: Ist mit Updates zu rechnen und in welchen Zyklen finden diese statt?
• Deinstallation: Wie kann das Programm sicher vom System entfernt werden?

Gerade bei Software, die mit einer Grafischen Benutzeroberfläche (GUI) arbeitet, sollte den Anwendern mittels Screenshots eine Orientierungshilfe geliefert werden. Ohne diese kann das Zurechtfinden für den User schnell unübersichtlich und frustrierend werden. Achten Sie darauf, dass diese durch Hervorhebungen klar zeigen, worum es geht, also etwa welcher Button geklickt werden muss.

Was sind Best Practices für Software-Dokumentation?

Es gibt keine allgemeingültige Antwort auf diese Frage, da die besten Praktiken für Software-Dokumentation je nach der zu dokumentierenden Anwendung und den Bedürfnissen der Zielgruppe variieren. Es gibt jedoch einige allgemeine Tipps, die bei der Erstellung von effektiven Software-Dokumentationen befolgt werden können:

1. Einfach und klar: Die Dokumentation sollte leicht verständlich und frei von Fachausdrücken sein, die der Zielgruppe nicht geläufig sind.
2. Prägnant sein: Nehmen Sie nur die wichtigsten Informationen auf und lassen Sie alles weg, was nicht direkt mit der Nutzung der Software zu tun hat.
3. Verwenden Sie Bildmaterial: Wenn möglich, verwenden Sie Bilder, Screenshots oder Diagramme, um den Text zu ergänzen und komplexe Konzepte zu erklären.
4. Logische Gliederung: Die Informationen sollten in einer konsistent und leicht verständlichen Struktur präsentiert werden.
5. Verwenden Sie eine einheitliche Formatierung: Achten Sie darauf, dass die Dokumentation durchgehend ein einheitliches Format verwendet, auch für Überschriften, Schriftarten usw.
6. Fügen Sie Links ein: Fügen Sie gegebenenfalls Links zu externen Ressourcen ein, die weitere Informationen zu einem bestimmten Thema liefern können.

Was gibt es bei einer Entwicklerdokumentation besonders zu beachten?

Bevor Sie beginnen Ihre Software zu erstellen, können Sie sich die Arbeit erleichtern und simultan mit dem Schreiben der Dokumentation beginnen. Dabei sollten Sie folgendes beachten:

1. Legen Sie fest, für welchen Anwendungszweck die Entwicklerdokumentation gedacht ist bzw. an welchen internen Entwicklerkreis sich diese richtet.
2. Von der Zielgruppe hängt auch der Umfang der Entwicklerdokumentation ab. Sie müssen daher vorab überlegen, welche Informationen, Ressourcen, Datenbanken und Kommentare zum Quellcode benötigt werden.
3. Entscheiden Sie, welche für Ihren Fall relevanten Inhalte abgedeckt werden sollen: Programmstruktur, Funktionen und Unterfunktionen, Auflistungen von Programmvariablen und verwendeten Dateien.
4. Beachten Sie Standards für die Dokumentation in der Programmiersprache, sofern diese wie etwa bei Java, Visual Basic oder C# existieren. Das kann das Arbeiten an einer Entwicklerdokumentation erleichtern, vor allem wenn mehrere Personen diese gleichzeitig bearbeiten.
5. Bei sehr langem Quellcode können Sie sich überlegen eine zusätzliche Hilfedatei anzulegen, in der relevante Schlüsselwörter referenziert werden.

Was gibt es bei einer Benutzerdokumentation besonders zu beachten?

Neben den weiter oben genannten Best Practices sollten Sie folgende Herangehensweise beachten:

1. Bestimmen Sie welche Form Ihre Benutzerdokumentation haben soll. Vom klassischen PDF bis zur Online-Hilfe: Sie haben viele Möglichkeiten die Informationen aufzubereiten.
2. Überlegen Sie sich genau, wer Ihre Zielgruppe ist. Sie müssen wissen, ob es sich um technikaffine, mit komplexen Programmen vertraute Spezialisten oder Gelegenheitsanwender handelt.
3. Passen Sie die Tiefe und Komplexität des Geschriebenen an diese Zielgruppe an. Manche Vorgänge müssen für eine unerfahrene Nutzergruppe intensiver beschrieben werden.
4. Beachten Sie die weiter oben genannten Punkte, die erklären, was in eine Software-Dokumentation gehört. Wenn diese Elemente vorkommen, müssen Sie auch beschrieben werden.
5. Zusätzlich sollten Sie häufig auftretende Anwendungsfälle als Handlungsanweisungen verfassen, die Schritt für Schritt erklären, was der Nutzer tun muss.

Welche Tools zum Erstellen einer Software-Dokumentation gibt es?

Welches die optimalen Werkzeuge zum Erstellen sind, hängt in erster Linie davon ab, welche Art von Software-Dokumentation entstehen soll. Neben Klassikern wie Microsoft Word oder Adobe Framemaker gibt es noch spezifischere Optionen. Im Folgenden finden Sie eine Liste verschiedener Möglichkeiten an Tools, um Software zu dokumentieren:

Help-Authoring-Tools

Ein Help Authoring Tool (HAT) ist eine Software zur Erstellung von Online-Hilfen und anderen Informationsdokumenten, oft auch druckbare Dokumente (PDF-Handbücher) in unterschiedlich guter Qualität. Diese sind vor allem für Benutzerdokumentation geeignet.

• MadCap Flare
• RoboHelp
• Help & Manual
• Help Studio
• HelpNDoc
• HelpSmith
• Doc-O-Matic Author
• Paligo
• ClickHelp
• Document360

DITA-basierte Tools

DITA-basierte Tools sind Werkzeuge, die auf der standardisierten XML-Struktur DITA basieren und speziell für die Dokumentation von Software entwickelt wurden. Sie sind sehr gut für große Dokumentationsprojekte geeignet. In der Regel ist die Arbeit mit ihnen aber zu komplex und zu teuer für kleinere Projekte unter einigen hundert Seiten.

• DITA Open Toolkit
• <oxygen/> xml Editor
• DocBook
• XMLmind DITA Converter (ditac)

Content-Component-Management-Systeme (CCMS)

Diese basieren entweder auf DITA oder funktionieren auf der Basis eigener Strukturen. Eher für sehr große Dokumentationsprojekte vorgesehen. Für Projekte unter tausend Seiten sind CCMS sehr kostspielig. Es kann sich aber auch bei einer gewissen Sprachanzahl schon für wenigere Seiten lohnen.

• Author-it
• easyDITA
• DITAToo
• XDocs DITA CCMS
• Vasont CMS
• Schema ST4

Konverter für bestehende Handbücher

Es ist auch möglich ein mit Word- oder FrameMaker erstelltes Handbuch in eine HTML-basierte Online-Hilfe umzuwandeln. Wenn Sie auf die Schnelle eine Online-Hilfe erstellen wollen, könnte ein Konverter zumindest für eine erste Version hilfreich sein. Auf Dauer sollten Sie sich allerdings um maßgeschneiderte Onlinehilfen bemühen. Denn konvertierte Dokumente bleiben im Grunde Handbücher, die nur auf den ersten Blick wie Online-Hilfen aussehen.

• WebWorks ePublisher

Teil-Automatisierte Dokumentationslösungen für kurze schrittweise Anleitungen

Sie können sich auch über teilautomatisierte Dokumentationslösungen eine Arbeitsgrundlage für eine Dokumentation erstellen lassen. Das funktioniert so: Sie führen Handlungen in einer Software aus, während das Dokumentations-Programm die Arbeitsschritte vermerkt und ganz automatisch eine Serie von Screenshots erzeugt. Mit diesen Daten wird dann eine Rohfassung der Dokumentation generiert. Das ist nur für schnelle Anleitungen und kleine Projekte empfehlenswert.

• SnagIt
• FlowShare
• ScreenSteps

Teil-Automatisierte Dokumentationslösungen für GUI-Referenzen

Derartige Programme sind in der Lage, Ressourcen eines Programms automatisch zu scannen und daraus Hilfe-Topics zu erstellen. Dabei legt das Tool Screenshots der Benutzeroberfläche (GUI) mit dazu gehörender Beschriftung an. Zusätzliche Informationen können dann nach belieben ergänzt werden. Grunddokumentationen lassen sich so schnell erzeugen. Gerade wenn nicht viel ausgegeben werden soll und wenig Zeit zur Verfügung steht, kann eine solche Lösung sinnvoll sein. Leider generieren diese Tools inhaltlich nur lückenhaftes Stückwerk, welches manuell ergänzt werden muss, vor allem bezüglich spezifischer Handlungsanleitungen.

• Dr. Explain

(Teil-)Automatisierte Dokumentationslösungen für API-Dokumentation

Diese Tools durchforsten den Quellcode nach Kommentaren und schaffen aus diesen ‒ meist als HTML ‒ eine API-Dokumentation. Wenn die Kommentare mit der API regelmäßige Updates erfahren, lässt sich so immer leicht der neuste Stand erzeugen. Hier gibt es viele gute frei verfügbare Open-Source-Lösungen. Nachteilig ist, dass eigene Inhalte sich nur mit Schwierigkeiten hinzufügen lassen. Diese Tools werden daher meist mit anderen Tools gemeinsam genutzt.

• Doc-O-Matic
• Slate
• Document! X
• Swagger
• Sphinx
• ReadMe
• NelmioApiDocBundle