Richtlinie für Entwickler und Designer

Neuer ISO-Standard für Software-Dokumentationen

01.10.2008
Von Nicolas Zeitler

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.

Zur Startseite