Foto: ISO
Wer Software-Anwendungen nutzt, braucht genaue Angaben darüber, wie ihm die Programme helfen, bestimmte Aufgaben zu erledigen. Die Dokumentation spielt dabei eine wichtige Rolle. Sie prägt den ersten Eindruck des Nutzers von einer Anwendung, wie die Standardisierungs-Organisation ISO im Vorwort zu ihrer Veröffentlichung ISO/IEC 26514:2008 schreibt. Der Standard trägt den Titel "Systems and software engineering - requirements for designers and developers of user documentation".
Häufig werde die Dokumentation als etwas angesehen, was man eben nach der Implementierung einer neuer Software auch noch erstellen müsse, merken die Autoren eingangs an. Sie plädieren für einen anderen Ansatz: Die Entwicklung einer wirklich hochwertigen Dokumentation sollte als fester Bestandteil im Lebenszyklus einer Software gelten.
Schritt für Schritt beschreibt der neue ISO-Standard, was der Entwickler einer Software-Dokumentation alles tun muss. Seine Arbeit beginnt damit, sich umfassend über das fragliche Projekt kundig zu machen. So muss er etwa fragen, welchem Zweck die Software dient und welches die Anwender-Zielgruppe ist.
Wichtig sind auch Angaben darüber, ob ein Programm für sich alleine steht oder Teil eines Softwarepakets ist, welche vorherigen Versionen es gab und auf welchen Plattformen die Anwendung laufen soll.
Um seine Dokumentation richtig zu konzipieren, muss ihr Ersteller ferner die Rahmenbedingungen für die Dokumentation im speziellen Fall kennen. Dabei muss er zum Beispiel die Frage klären, ob es in einer Organisation Richtlinien für die Dokumentation gibt. Auch rechtliche Bestimmungen sind zu beachten: Datenschutzregelungen ebenso wie sonstige Regelungen des nationalen Rechts im jeweiligen Land.
Anwender muss in 20 Sekunden das Gewünschte finden
Die angestrebte Zahl an verkauften Software-Lizenzen sollte der Entwickler einer Dokumentation ebenfalls kennen. Auch über sonstige Eckdaten muss er im Bilde sein: Wann genau wird eine Software veröffentlicht? Kommt sie weltweit zum gleichen Zeitpunkt auf den Markt? Wie lange vor dem Auslieferungsdatum muss die Dokumentation fertig sein?
Der ISO-Standard mahnt auch Benutzerfreundlichkeit an. Hier werden zum Teil ganz konkrete Kriterien genannt. So gelten Struktur und Navigation einer Dokumentation dann als annehmbar, wenn ein Anwender darin innerhalb von 20 Sekunden die Informationen findet, die er sucht.
Verbindliche Zeitpläne vereinbaren
Um an die entscheidenden Angaben über eine Software-Neuentwicklung zu kommen, rät die Standardisierungs-Organisation den Entwicklern dazu, mit den beteiligten Fachleuten strukturierte Interviews zu führen. Gemeinsam mit Software-Entwicklern und Projektmanagern sollte der Autor der Dokumentation sich auf allgemein verbindliche Zeitpläne verständigen.
Alles bisher Beschriebene sind zunächst nur die Vorarbeiten. Als nächsten Schritt schreibt ISO/IEC 26514:2008 eine Analyse vor. Darin geht es zum Beispiel darum, sich eingehend mit den späteren Lesern auseinanderzusetzen. Der Verfasser der Dokumentation muss wissen, mit welchem Vorwissen er bei den Anwendern rechnen kann, wie gut etwa deren Englischkenntnisse sind, aber auch, wie häufig sie mit der fraglichen Anwendung arbeiten.
Anschließend muss der Autor der Dokumentation erheben, was genau die Nutzer mit der Software anfangen. Falls sie noch im Entwicklungsstadium ist, muss er überlegen, welche Aufgaben welche Gruppe von Nutzern wahrscheinlich damit erledigen wird. Auf Grundlage all dieser Erhebungen richtet sich dann das Design der Dokumentation.
Umfangreiche Qualitätskontrollen
Im Anschluss beginnt dann die eigentliche Arbeit, die Texte und Grafiken für die Dokumentation zu erstellen. Qualitätskontrolle spielt dabei eine große Rolle. So soll ein Vorgehen zur Evaluierung der Dokumentation ausgearbeitet werden. Dabei müssen die unterschiedlichen Sichtweisen der Beteiligten berücksichtigt werden: Die Entwickler sehen die Software durch eine andere Brille als Anwender oder das Management.
Vorgesehen sind des weiteren Verfahren zur inhaltlichen Überprüfung der Dokumentation. Sie sollte nach verschiedenen Kriterien überprüft werden: Ist sie technisch korrekt, werden Sicherheitsbelange genügend berücksichtigt, ist sie leicht zu verstehen, ist sie in sich schlüssig, fehlt nichts, entspricht sie den gültigen Rechtsvorschriften? Wer an einer Durchsicht anhand dieser Kriterien beteiligt werden soll und wie sie abzulaufen hat, sollten der Autor und der Projektmanager gemeinsam festlegen.
Tests parallel zur Anwendungsentwicklung
Als nächster Schritt folgt dann ein Test der Dokumentation in Verbindung mit der Software. Er ist Aufgabe des Teams, das die Dokumentation erstellt. Laut ISO sollte die Dokumentation in jeder Phase der Anwendungsentwicklung getestet werden, sofern die Software zum jeweiligen Zeitpunkt verfügbar ist. Dabei stehen Fragen im Mittelpunkt wie: Stimmen die Querverweise? Wird in bestimmten Situationen die richtige Information angezeigt? Haben die Anweisungen in der Dokumentation den gewünschten Erfolg?
Als letztes Testverfahren ist schließlich ein Benutzerfreundlichkeitstest mit den späteren Anwendern der Dokumentation vorgesehen. Er ist laut ISO die am meisten anerkannte Methode um festzustellen, ob die in der Dokumentation enthaltene Information wirklich das ist, was die Nutzer brauchen.
Unter dem Stichwort "Produktion" listet der ISO-Standard im Anschluss die Schritte auf, in denen die Dokumentation letztlich zusammengestellt wird. Texte sind Korrektur zu lesen, alle Querverweise nochmals zu überprüfen. Außerdem muss die Gliederung nochmals durchgesehen werden: Sind alle Überschriften und Untertitel korrekt durchnumeriert?
Zahl der Gliederungsebenen begrenzen
Besonderes Augenmerk liegt auf der Struktur der Dokumentation - erscheint diese nun gedruckt oder als Online-Hilfe. Die Autoren sollten ihr Werk so zusammenstellen, dass sich dem Nutzer erschließt, was er wo findet. Die ISO rät dazu, nicht mit zu vielen Gliederungsebenen zu arbeiten. Bei Dokumentationen, die die Anwender am Bildschirm lesen, sollte keine Information weiter als drei Ebenen von der übergeordneten Seite zu einem Thema entfernt sein.
Zur Nutzerfreundlichkeit kann der Dokumentations-Autor beitragen, indem er für eine möglichst übersichtliche Darstellung sorgt. Am Bildschirm zu lesende Dokumente sind demnach dann besonders leserfreundlich, wenn man sie ganz lesen kann, ohne in der Bildschirmansicht abwärts rollen zu müssen.
Lange Dokumentationen brauchen Suchfunktion und Index
Je nach Umfang der Dokumentation sind einzelne Bestandteile Pflicht oder wahlweise einzufügen. So sollte eine ungedruckte Dokumentation auf jeden Fall mit einer Suchfunktion ausgestattet sein, wenn sie länger als acht Seiten ist. Ein Index sollte immer dann vorhanden sein, wenn ein Dokument mehr als 40 Seiten umfasst. Zu den Pflichtbestandteilen gehören auf jeden Fall eine Einführung für den Leser und eine Übersicht über mögliche Fehlermeldungen und Problemlösungen.
Die letzten beiden Kapitel des Standards widmen sich dem Inhalt und dessen Aufbereitung. So wird zum einen beschrieben, was alles in einer Dokumentation enthalten sein muss - etwa mögliche Fehlermeldungen - und wie der Inhalt verständlich aufbereitet wird. "Ein simples Vokabular, mit dem die Anwender vertraut sind" ist demnach ratsam. Aufforderungen an den Nutzer sollten im Imperativ formuliert werden, sofern dieser in der jeweiligen Sprache existiert.
Das letzte Kapitel im ISO-Standard ISO/IEC 26514:2008 beschreibt ausführlich die Gestaltungsrichtlinien für eine Dokumentation. Es geht dabei zunächst um die Wahl des geeigneten Formats - soll eine Dokumentation gedruckt werden oder genügt es, sie am Bildschirm zur Verfügung zu stellen?
Auch umfassende Angaben zum Layout werden dargestellt. So sollte die Wahl der Schriftgrößen für Überschriften die Hierarchie in der Gliederung deutlich machen. Der Gestalter einer Dokumentation sollte zudem zurückhaltend beim Gebrauch von Farben sein. Gehe es um Themen, die graphischer Erklärungen bedürfen, sei es oft unerlässlich, mit verschiedenen Farben zu arbeiten. Ansonsten sollten bunte Akzente eher spärlich gesetzt und zur Betonung einzelner Begriffe verwendet werden, um den Leser nicht vom Wesentlichen abzulenken.