© pixelhunter17 / 123rf.com

Ein Erfolgsfaktor für gute Dokumentation ist eine strukturierte und systematische Herangehensweise. Dieser Beitrag vermittelt Grundlagenwissen darüber, wer was und wie dokumentieren sollte und wie man dabei den roten Faden nicht verliert.

Wen sollte man fragen, wenn man sich einen Überblick über Softwaredokumentation verschaffen will? Am besten vielleicht die Berufsgruppe, die sich ganz dem Thema der Dokumentation verschrieben hat: die Technischen Redakteure. Einen Technischen Redakteur zeichnet besonders aus, dass er nicht irgendeinen Text verfasst, sondern einen, der nützliche Informationen zum Produkt – in diesem Fall zur Software – so zusammenfasst, dass der Leser sie leicht aufnehmen kann. Zu diesen nützlichen Informationen gehören jegliche für die Zielgruppe relevanten Daten, die für die Entwicklung, Nutzung, Pflege und Unterhaltung sowie Aktualisierung notwendig sind.

Und schon ist da ein für die Dokumentation außerordentlich relevantes Stichwort aufgetaucht: Zielgruppe. Sobald es etwas zu dokumentieren gibt, rücken auch diejenigen in den Fokus, die mit den Informationen umgehen müssen. Daher stellt sich für Technische Redakteure neben dem Was auch gleichzeitig die Frage: Für wen ist zu dokumentieren? Schon allein dieses Kriterium unterteilt Technische Dokumentation in verschiedene Kategorien.

Außerdem kommt es noch auf die Form an: Wie wird dokumentiert? Das kann Text sein, Illustrationen, Grafiken, Mindmaps und so weiter. Je nach Art der Dokumentation kann sie entweder in den Quellcode eingebettet sein oder die Software begleiten. Wichtig ist, die Informationen so aufzubereiten, dass sich nachvollziehen lässt, wie das Softwareprogramm zu verwenden ist. Der Zweck der einzelnen Komponenten sollte klar werden und auch ein Überblick über die Möglichkeiten (und Grenzen) des Programms gegeben werden. Je nachdem, was die Software alles kann, gehört auch dazu, dass die Funktionsweise erklärt wird. Das betrifft unter Umständen auch Resultate oder Prozesse, an denen die Software beteiligt ist. Es gilt, zu erläutern, wie das Programm zu bedienen ist, welche technischen Voraussetzungen notwendig sind und welche Tätigkeiten gegebenenfalls sonst noch auszuführen sind.

Immer wieder höre ich als Technische Redakteurin von Softwareentwicklern, dass der Code doch schon ausreichend erkläre, was da passiert. Das kann für jeden, der sich den Quellcode ansieht, auch durchaus eine theoretische Möglichkeit sein. Aufs Ganze gesehen ist das aber etwas zu kurz gedacht. Schauen wir also zuerst einmal genauer darauf, welche Arten von Softwaredokumentation es gibt: Dann wird klar, dass der Code allein nicht die komplette Doku sein kann (Abbildung 1).

Abbildung 1: Das sind die Bausteine interner und externer Softwaredokumentation.

Interne Dokumentation

Generell unterscheidet man zunächst zwischen interner und externer Dokumentation. Interne Dokumentation bezeichnet all das, was beim Softwarehersteller verbleibt. Das ist nicht weniger wichtig, häufig ist allerdings die Form etwas freier. Vor allem muss diese Art von Dokumentation nicht mit dem Marketing abgestimmt werden. Auf diesen Umstand kommen wir bei der externen Doku zurück.

Ganz zu Beginn eines Projekts stehen häufig die Anforderungen, was die neu zu entwickelnde Software denn tun soll. Manche kennen das unter dem Namen Lastenheft. Teilweise wird diese Dokumentation auch agil erweitert, weil im Entstehungsprozess nicht von Anfang an alle Details klar sind. Bevor es dann ans Coden geht, wird – mal genauer, mal grober, mal agil und schrittweise, mal als ein großes Ganzes – festgelegt, wie diese Anforderungen umzusetzen sind. Das ist dann entweder als einzelne Tasks notiert oder bildet ein ganzes Pflichtenheft. Das hängt immer davon ab, wie umfangreich die Software ist, ob es spezifische vertragliche Bedingungen gibt und ob der Kunde eine ausführliche Antwort vor Programmierbeginn wünscht – um nur einige Faktoren zu nennen, von denen die Art und Weise abhängt.

Meistens wird ein großer Teil der internen Dokumentation von den Softwareentwicklern selbst erstellt. Hier ist also die Aussage gar nicht so weit hergeholt, dass der Code die Doku sei. Allerdings kann das nur gelingen, wenn der Code mehr als die reine Aneinanderreihung von Funktionen ist. Das bedeutet, dass bestimmte Komponenten oder Abschnitte mit Kommentaren versehen sein sollten. Nur so kann man sie auch als dokumentiert ansehen. Das Ergebnis bezeichnet man dann häufig auch als Entwicklerdokumentation. Diese Doku richtet sich vor allem an die Zielgruppe der Programmierer, die künftig an dem Code arbeiten sollen oder müssen. Sie umfasst Informationen über Architektur, Codestruktur und Verwendung der verschiedenen Funktionen des Programms.

Neben der Entwicklerdokumentation gibt es, sofern die Software Daten benötigt oder erzeugt, auch die sogenannte Datendokumentation. Hier ist es wichtig, dass klar wird, welche Daten das Programm benötigt, um zu funktionieren. Was ist wie eingebettet, was wird wo abgelegt und welche Daten kommen als Output heraus? Falls die erzeugten Daten an bestimmten Stellen zu speichern sind, braucht es dann spezifische Formate?

Wenn es um umfangreichere Software geht, kann es sein, dass zusätzlich eine Installationsdokumentation erstellt werden muss. Sie sollte nachvollziehbar beschreiben, wie und in welcher Reihenfolge Systemkomponenten installiert und eingerichtet werden müssen, damit am Ende die Gesamtfunktion gewährleistet ist.

Etwas, das auch für kleinere Programme durchaus hilfreich sein kann, ist die Testdokumentation. Jeder Entwickler kennt das nur zu gut: Das Programm läuft super, man ändert an einer Stelle eine winzige Kleinigkeit – und schon treten Fehler auf. Hier hilft die Testdokumentation. Sie beschreibt die erforderlichen Tests, um die korrekte Funktion der Software zu überprüfen. Dazu gehört selbstverständlich auch, wie die Tests angelegt sind, worauf die Ergebnisse schließen lassen und wie mögliche Fehler, die in den Tests aufgefallen sind, beseitigt wurden. So lässt sich am Ende auch nachweisen, dass man alles dafür getan hat, dass die Software sicher und stabil läuft.

Neben diesen sehr eng mit dem tatsächlichen Fortschritt bei der Softwareentwicklung verknüpften Dokumenten ist eine Projektdokumentation dafür da, die Planung und Organisation der Entwicklung festzuhalten. Dabei können beispielsweise geplante Ziele, genutzte Tools und Herangehensweisen beschrieben werden. Diese Art der Dokumentation geschieht häufig nebenbei und in Projekt-Meetings, weil mehrere Schritte mit mehreren Beteiligten zu absolvieren sind, in denen die neuen Aufgaben und Teilschritte zugewiesen werden.

Als letzten Punkt für die internen Dokumente wollen wir noch die Systemdokumentation anreißen. Sie beschreibt ein komplexeres System mit all seinen Komponenten, Funktionen und deren Zusammenwirken. Die Qualität dieser Dokumentation kann entscheidend dafür sein, ob der Technische Redakteur für die externe Dokumentation erneute Recherchen zu diesem Thema betreiben muss oder ob er das als Grundlage für die Darstellung der Zusammenhänge bei der externen Dokumentation verwenden kann.

Externe Dokumentation

Die externe Dokumentation richtet sich an die Verwender der Software, die häufig nicht an der Entwicklung beteiligt waren. Deshalb geht es für den Technischen Redakteur nicht nur darum, den Entwicklern die Informationen aus der Nase zu ziehen. Stattdessen muss er sich auch mit den Abteilungen abstimmen, die mit dem Kunden zu tun haben. Das ist einerseits das Marketing, das das Unternehmen oder die Produktmarke nach außen optimal repräsentieren möchte, andererseits aber auch der Vertrieb, der mit dem Kunden unter Umständen spezifische Abmachungen – auch bezüglich der Dokumentation – getroffen hat.

Externe Dokumentation sollte hilfreich sein, um zu verstehen, wie ein Programm zu verwenden und zu konfigurieren ist. Manchmal ist sie aber auch eine Quelle der Verwirrung und Frustration für ihre Leser. Das gilt vor allem dann, wenn sie nicht sinnvoll redaktionell aufbereitet, verständlich geschrieben oder nachvollziehbar strukturiert ist. Also ist gerade hier die Gilde der Technischen Redakteure gefragt, das Wissen einerseits zu sammeln, andererseits auch zu analysieren und zu strukturieren – und vor allem: es verständlich für die jeweilige Zielgruppe wiederzugeben.

Zur externen Softwaredokumentation gehört zum Beispiel die klassische Benutzerdokumentation oder das Benutzerhandbuch, als PDF oder gedruckt, so wie es früher üblich war und es manche Verträge immer noch fordern. Die Handbuchinhalte sollten sich nicht wesentlich von der Online-Hilfe oder kontextsensitiven Hilfe unterscheiden. Häufig ist hier hauptsächlich die Art der Darstellung anders. Der digitale Raum bietet auch Möglichkeiten, die Inhalte spezifischer zu filtern als das in einer gedruckten oder PDF-Version möglich wäre. Als Beispiel zeigt Abbildung 2 die Word-Hilfe von Microsoft. Mit einem Klick auf das kleine Fragezeichen öffnet sich direkt die Online-Hilfe, die unter http://support.microsoft.com zu finden ist. Sie enthält Screenshots, damit sich der Benutzer schnell zurechtfindet, sowie Handlungsanweisungen oder Tätigkeitsbeschreibungen (mit fett dargestellten Bezeichnungen aus der Software selbst) und Tipps & Tricks.

Abbildung 2: Aus diesen Elementen besteht die Online-Hilfe von MS-Word.

Eine weitere Möglichkeit, wie Informationen zum Anwender gelangen können, sind Leitfäden und Tutorials, die nicht alle Funktionen der Software abdecken, sondern nur spezifische Themen – die aber dafür sehr detailliert. Falls die Software über Drittanbieter auf den Markt kommt oder mit weiteren Programmen oder Daten interagieren soll, ist eine API-Dokumentation für die Schnittstellen unabdingbar. Sie erklärt vor allem, wie man die Schnittstelle nutzt und in welchen Formaten und auf welche Art sie die Daten überträgt. Hier kann teilweise Datendokumentation schon hilfreich sein.

Je nachdem, was der User mit der Software alles tun darf und kann, sind weitere Informationen unbedingt nötig. So kann auch für den Administrator, der sich beim Kunden um die Einrichtung der Software kümmert, eine Testdokumentation hilfreich sein, sofern die Software Schnittstellen mitbringt und in Prozesse eingreifen könnte.

Entlang des Lebenszyklus

Alles in allem kann man sich auch bei der Softwaredokumentation an den Produktlebenszyklus halten. Von der Installation und Konfiguration über die Benutzung und Anpassungsmöglichkeiten bis hin zum Aktualisieren und Updaten und letztlich zur Deinstallation gibt es fast immer etwas, was der Nutzer wissen muss.

Die Installationsanleitung sollte beantworten, wie man das Programm auf einem Rechner einrichtet und welche Voraussetzungen erfüllt sein müssen. Meist richtet sich diese Anleitung an erfahrene Administratoren, die mit klassischem Softwarejargon gut klarkommen. Im Gegenzug dazu gehört in die Deinstallationsanleitung, was getan werden muss, um die Software sicher vom System zu entfernen, und ob es etwas zu beachten gilt, damit beispielsweise erzeugte Daten erhalten bleiben.

Auch die Konfigurationsanleitung wendet sich häufig noch an Administratoren. Sie beschreibt die Einstellungsmöglichkeiten und -empfehlungen, damit die User die Software dann bestmöglich nutzen können. Dazu kann auch gehören, wie sich einer Fehlbedienung vorbeugen lässt, sodass keine wichtigen Informationen verloren gehen. Auch häufig auf der Ebene für Admins angesiedelt sind die Informationen für Updates und Aktualisierungen, besonders bei komplexeren Programmen. Falls Anwender Updates direkt ausführen dürfen, dann muss die Dokumentation klar und verständlich beschreiben, wie das Schritt für Schritt funktioniert. Außerdem stünde hier, ob es feste Zyklen für Updates gibt.

Benutzerdokumentation richtet sich, wie der Name schon sagt, an die User, die mit dem Programm arbeiten sollen. Sie zeigt auf, welche Möglichkeiten die Software bietet und wie man sie verwendet. Gerade bei Software mit einer grafischen Benutzeroberfläche (GUI) sollten Screenshots den Anwendern eine Orientierungshilfe liefern. Ohne sie findet sich der User schnell nicht mehr zurecht und ist frustriert. Achten Sie darauf, dass Hervorhebungen klar aufzeigen, worum es geht, also zum Beispiel, welcher Button geklickt werden muss.

Besonders wichtig ist auch das Thema der Fehlerbehebung: Mit welchen Fehlern muss man rechnen, und wie behebt man sie? Gegebenenfalls gehört auch dazu, wer den Fehler behebt, falls der User das nicht selbst kann oder sogar der Admin passen muss, weil eine Konfiguration ausschließlich in der Hand des Herstellers liegt.

Häufig möchte vor allem der Vertrieb die Beschreibung der Anpassungsmöglichkeiten in jede Benutzerinformation integrieren, damit der Kunde möglichst weitere Funktionen zukauft. Durch Addons können in diesem Fall mehr Dinge mit einem Programm erledigt werden, die dann allerdings häufig extra zu vergüten sind.

Anforderungen

Woher können Anforderungen an die Doku kommen? Zunächst gilt: Die Anforderungen an die Dokumentation von Software unterscheiden sich nicht wesentlich von Anforderungen an andere Dokumentationsarten. Grundsätzlich gilt es, die Regeln der Technischen Dokumentation einzuhalten:

• Die Dokumentation soll die Fragen der jeweiligen Zielgruppe beantworten. Dazu gehört etwa die Frage der User, wie das Programm genutzt wird oder die der Entwickler, wofür welcher Teil im Code steht.
• Die Doku soll verständlich sein, dabei aber trotzdem so kurz wie möglich.
• Softwaredokumentation muss sich nach den Bedürfnissen und Aufgaben der Endanwender richten.
• Die Dokumentation erfolgt meist zusammen mit der Software.
• Auch die Doku muss möglichen rechtlichen Anforderungen genügen. Das gilt insbesondere, wenn die Software Teil eines Gesamtprodukts ist. Dann gelten die gleichen Regeln wie für die Hardware.
• Mögliche vertragliche Vereinbarungen gehören ebenfalls zum rechtlichen Rahmen der Softwaredokumentation. Es gibt aber auch Anforderungen aus Normen, die versuchen, die Informationen für die Benutzung zu vereinheitlichen. Sie beschreiben konkrete Rahmenbedingungen, auf die sich Experten aus dem Fachgebiet geeinigt haben, damit der Standard – in diesem Fall für die Dokumentation – einheitlich und qualitativ hochwertig ist.

Es existieren verschiedene Herangehensweisen, um eine passende Benutzerdokumentation zu erstellen. Das bezieht sich auf aktuell gebräuchliche Methoden, an denen man sich als Dokumentierender orientieren kann. Wohl jeder Technische Redakteur hat die Zahlenfolge 82079-1 schon einmal gehört oder gesehen. Dahinter verbirgt sich eine international entwickelte Norm, die auf Deutsch beim DIN herausgekommen ist. Daneben haben das europäische Normengremium EN sowie internationale Organisationen wie IEC und IEEE mitgewirkt. Hier liegt der Fokus auf der Informationsvermittlung durch die Dokumentation für jegliche Produktarten. Diese Norm ist also für eine professionell erstellte Dokumentation generell relevant.

Außerdem lässt sich für den Bereich der Softwaredokumentation die Normenreihe ISO/IEC/IEEE 2651x mit Bezug auf Nutzerinformationen heranziehen. Die einzelnen Normteile sprechen die jeweiligen Kontaktgruppen der Benutzerinformation (vom Manager, Einkäufer und Lieferanten, Tester und Gutachter bis zum Designer und Entwickler) und die agile Vorgehensweise an.

Wer schreibt?

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

Bei der internen Dokumentation war dagegen häufiger vom Entwickler/Programmierer die Rede. Viele Entwickler erarbeiten die Softwaredokumentation selbst. Wer programmiert hat, weiß genauestens, wie die Software funktioniert. Das kann aber auch dazu führen, dass die Erklärung den technischen Horizont der Anwender oder neu eingestiegener Entwickler weit übersteigt. Beim Erstellen der externen Dokumentation durch die Entwickler können leicht technische Details erwähnt werden, die eher verwirren als helfen. Um eine Software zu verwenden, muss der User die Feinheiten der inneren Funktionsweise meist nicht kennen, sondern nur genau wissen, wie Dinge zusammenhängen und welche Reihenfolge er im Fall der Fälle zu beachten hat.

Es kann aber auch sein, dass Fachanwender Software dokumentieren. Da sie regelmäßig mit der Software arbeiten, wissen sie in der Regel, was andere Anwender an Informationen benötigen. Allerdings sind solche Nutzer eher ein Glücksfall. Softwareentwickler sollten sich nicht darauf verlassen, dass Benutzerdokumentation auf diese Weise entsteht. Es kommt jedoch durchaus vor, dass Anwender einzelne, spezifische Use Cases verbreiteter Software etwa in Foren besprechen.

Im Idealfall dokumentiert also weder der Technische Redakteur noch der Entwickler allein die Software. Eine gute Mischung und Arbeitsteilung ermöglicht maximale Effizienz bei bestmöglichem Effekt.

Wie ist zu dokumentieren?

Es gibt keine allgemeingültigen Best Practices für Softwaredokumentation, da diese davon abhängt, was genau für wen dokumentiert werden muss. Trotzdem gibt es einige allgemeine Tipps für die Doku eines Programms:

• Einfach und klar: Leicht verständlich formulieren und je nach Zielgruppe frei von Fachausdrücken, sofern sie nicht geläufig sind.
• Prägnant: Nur für die Zielgruppe relevante Informationen dokumentieren und für das User Manual zum Beispiel alles weglassen, was nicht direkt mit der Nutzung der Software zu tun hat.
• Bilder: Verwenden Sie möglichst Bildmaterial wie Screenshots oder Diagramme, um den Text zu ergänzen und komplexe Konzepte zu erklären.
• Logische Gliederung: Wenn die Struktur konsistent und leicht verständlich ist, lassen sich die Informationen schneller finden und aufnehmen.
• Einheitliche Formatierung: Wenn gleiche Informationseinheiten gleich aussehen, sind sie schnell wiederzufinden.

Anwender schätzen Links zu externen Ressourcen, die zu einem bestimmten Thema weiterführende oder detailliertere Informationen liefern.

Praktische Tipps

Entwickler erleichtern sich die Arbeit, wenn sie von Anfang an auch an der Dokumentation arbeiten. So türmt sich nicht hinterher ein Berg Arbeit auf. Dafür muss klar sein, welchen Anwendungszweck die Dokumentation hat beziehungsweise an welchen internen Entwicklerkreis sie sich richtet. Von dieser Zielgruppe hängt auch der Umfang der Dokumentation ab. Daher gilt es, vorab zu überlegen, welche Informationen, Ressourcen, Datenbanken und Kommentare zum Quellcode benötigt werden.

Ein paar Beispiele für Inhalte sind Programmstruktur, Funktionen und Unterfunktionen, Auflistungen von Programmvariablen und zur Verwendung von Dateien. All diese müssen freilich nicht nur in der Entwicklerdokumentation enthalten sein, die Information kann auch in weiteren internen Dokumenten stehen.

Wenn man im Code dokumentiert, ist es wichtig, auch möglicherweise existierende Standards für die Dokumentation in der Programmiersprache zu beachten, wie etwa bei Java, Visual Basic oder C#. Oft hilft bei besonders langem Quellcode eine zusätzliche Hilfedatei, in der relevante Schlüsselwörter referenziert werden.

Bei der externen Dokumentation sollte zuerst die Form der Dokumentation definiert werden. Ob klassisches gedrucktes Handbuch, PDF oder Online-Hilfe: Es gibt viele Varianten, die Informationen für die Softwarenutzung aufzubereiten. Auch hier ist die Zielgruppe maßgeblich. Sind die Nutzer selbst Softwareentwickler oder technikaffin? Sind sie mit komplexen Programmen vertraute Spezialisten? Oder handelt es sich bei den Usern der Software um Gelegenheitsanwender? Daran muss die Detailtiefe und Komplexität der Dokumentation angepasst werden. Es gibt immer wieder Vorgänge, die man für unerfahrene Nutzer sehr genau beschreiben muss.

Klären Sie auch, welche Inhalte es genau bereitzustellen gilt und ob es unterschiedliche Zielgruppen gibt (Abbildung 3). Für häufig auftretende Anwendungsfälle ist eine Schritt-für-Schritt-Handlungsanweisung hilfreich, die den Nutzer genau anleitet.

Abbildung 3: Die Zielgruppendefinition anhand von Rollen und Zielen.

Tools

Auch wenn feststeht, was und für wen geschrieben wird, bleibt möglicherweise noch die Frage offen, mit welchem Tool die Doku erstellt wird. Hier wollen wir vor allem die externe Dokumentation betrachten, deren Aussehen und Form auch den Eindruck der Software beim User beeinflussen kann. Bei den hier aufgezählten Tools handelt es sich um eine rein zufällige Auswahl – es gibt viel mehr Werkzeuge, als wir hier aufzählen können.

Es liegt auf der Hand, Technische Dokumentation mit Autoren-Tools wie Microsoft Word oder Adobe Framemaker zu erstellen. Doch gerade für Software gibt es viele weitere Möglichkeiten. Da sind beispielsweise Help Authoring Tools (HAT) wie Madcap Flare oder Adobe Robohelp. Dahinter verbirgt sich Software zur Erstellung von Online-Hilfen und anderen Informationsdokumenten, die oft auch druckbare Dokumente (PDF-Handbücher) in unterschiedlich guter Qualität ermöglicht.

Bei DITA-basierten Tools wie etwa DITA Open Toolkit handelt es sich um Werkzeuge, die auf der standardisierten XML-Struktur DITA basieren und speziell für die Dokumentation von Software entwickelt wurden. Sie eignen sich sehr gut für große Dokumentationsprojekte. In der Regel ist die Arbeit mit ihnen aber komplex und teuer, der Nutzen für kleinere Projekte unter einigen Hundert Seiten ist daher fraglich.

Content-Component-Management-Systeme (CCMS) oder auch Redaktionssysteme wie Author-it oder Schema ST4, basieren entweder auf DITA oder funktionieren auf Basis eigener Strukturen. Sie sind eher für sehr große Doku-Projekte vorgesehen. Für Projekte mit weniger als 1000 Seiten sind CCMS sehr kostspielig. Sie können sich aber bei einer gewissen Anzahl von Zielsprachen schon für weniger Seiten lohnen.

Es ist auch möglich, ein mit Word oder Framemaker erstelltes Handbuch in eine HTML-basierte Online-Hilfe umzuwandeln. Soll auf die Schnelle eine Online-Hilfe erstellt werden, könnte ein Konverter wie Webworks ePublisher zumindest für eine erste Version hilfreich sein. Unabhängig davon, welche Tools Sie wählen, sollten Sie immer daran denken, dass Softwaredokumentation – wenn sie denn gut ist – die Effizienz neuer Entwickler bei der Einarbeitung in den Code sowie die Zufriedenheit Ihrer Kunden erhöhen kann. Das senkt vielleicht sogar die Zahl der Anfragen bei der Service-Hotline. (jcb)