08.08.2016

Softwaredokumentation: eine Frage des Stils

Anders als beispielsweise in der Luftfahrt existieren im Softwarebereich nur wenige industrieweite Vorgaben für die Dokumentation. Vorhandene Normen (z.B. ISO/IEC 26514) stellen zwar gewisse Rahmenbedingungen auf (u.a. Mindestinhalte und Vorgaben für die Printversion), lassen aber viele Fragen offen: Wie werden die Bedienelemente einer Software-Oberfläche bezeichnet? Welche Satzkonstruktionen sind angemessen?

Die "Großen" der Branche, allen voran Microsoft und Apple als Hersteller von Betriebssystemen, haben diese Fragen in eigenen "Style Guides" geregelt. Es handelt sich hierbei um Publikationen, die in erster Linie an Redakteure aus dem eigenen Hause gerichtet sind. Ziel ist es, dass alle an der Dokumentation beteiligten Personen einen einheitlichen Stil verwenden.

Auch für diejenigen, die Software zur Verwendung im jeweiligen Betriebssystem dokumentieren, lohnt sich ein Blick in den jeweiligen Style Guide. Somit ist sichergestellt, dass z.B. die Terminologie im Handbuch einer Anwendungssoftware und in der Online-Hilfe des verwendeten Betriebssystems nicht im Widerspruch zueinander stehen.

Der Style Guide von Apple ist kostenlos online verfügbar, regelt aber fast ausschließlich Bezeichnungen und Schreibweisen. Microsoft hat seinen Style Guide umfassender gestaltet und bietet auch Hinweise zu Grammatik und Zeichensetzung. Das "Microsoft Manual of Style" ist als Buch über den regulären Buchhandel erhältlich und sozusagen das Standard-Werk zur Software-Dokumentation für Programme auf Windows-Plattformen.

Ein weiteres sehr interessantes Beispiel ist der GNOME Documentation Style Guide, der die Dokumentation einer Benutzeroberfläche für Linux-Umgebungen vereinheitlichen soll. Er weist eine ähnliche Tiefe auf wie der Style Guide von Microsoft und steht kostenlos zur Verfügung. GNOME beschränkt beispielsweise die Satzlänge auf unter 25 Wörter.

Auch Software-Hersteller, die nicht an Betriebssystemen beteiligt sind, können natürlich eigene Vorgaben zu Qualitätsstandards für Ihre Dokumentationen treffen. In Fragen der Terminologie ist es aber sinnvoll, sich an die jeweiligen Style Guides der Betriebssysteme anzulehnen.

Style Guides sind aber auch in anderen Bereichen wie der ASD S1000D Dokumentation vorgeschrieben. Hierbei arbeiten verschiedene Teams, meist an unterschiedlichen Orten, an einem Projekt zusammen. Dies ist nur möglich, wenn alle denselben Regeln und Vorgaben folgen.

Wir unterstützen Sie gern.

Die ASN erstellt als Dienstleister im Bereich Technische Dokumentation für Sie neben Betriebs- und Gebrauchsanweisungen auch elektronische Teilekataloge, Servicedokumentation und Reparaturhandbücher, Handbücher für Software sowie interaktive Hilfesysteme und Online-Hilfen. Die Ermittlung und Anwendung relevanter Normen, Richtlinien oder Style Guides ist dabei selbstverständlich. Brauchen Sie bei der Durchführung Ihrer Projekte Unterstützung, sprechen Sie uns gerne an.