18.07.2017

Veröffentlichung vom 12.01.2005

Software-Anwender - also Sie und ich - sind eigenwillige Menschen. Und sie (also wir) wissen genau, was sie wollen: "Die Anwender erwarten eine Punkt-für-Punkt-Anweisung, die in sich schlüssig, kurz und klar formuliert sein sollte" Dies war das Ergebnis eines professionellen Anwendertests, über den die Fachzeitschrift "technische kommunikation" in ihrer jüngsten Ausgabe berichtet . Wie schaltet man die automatische Eingabe aus? Ehe man die Antwort im Handbuch oder in der Online-Hilfe gefunden hat, probiert man die Menüs durch: Extras - Zellinhalte - Autoeingabe: Häkchen wegklicken. Das hätte die Dokumentation fix preisgeben sollen. Gute Technikredakteure ärgern ihre Leser nicht immer wieder. Sie schreiben funktionierende Software-Dokumentation nach dem Stand der Technik, d. h. nach internationalen Normen.

Von Wolfram W. Pichler

Inhalte

Bewährte Schreibregeln

ISO-Normen als Fachbuch-Ersatz

Projektmanagement für Software-Dokumentation

Redaktionsrichtlinien für Software-Dokumentation

Online-Hilfe

Software Dokumentation bewerten

Software-Dokumentation kalkulieren

Fazit

Bewährte Schreibregeln

Diese Erkenntnis gehört allerdings seit je her zu den goldenen Regeln des Kunsthandwerks Technische Dokumentation:

Halte Dich an den Redaktionsleitfaden. Gibt es noch keinen? Erstelle ihn zusammen mit deinen Kollegen.

Schreibe zielgruppenorientiert.

Beschreibe Aufbau, Struktur und Funktion des Produkts, wenn Anwender Zusammenhänge verstehen wollen.

Gib Schritt-für-Schritt-Anleitungen, wenn Anwender Aufgaben bearbeiten wollen.

KISS (Keep it short and simple; schreib es kurz und einfach).

Fachbücher predigen Solches seit Jahrzehnten, neuerdings aber auch internationale Normen: DIN EN 62079 regelt Inhalt und Darbietung für Anleitungen aller Art, im Prinzip also auch für Software-Dokumentation.

ISO-Normen als Fachbuch-Ersatz

Für Software-Dokumentation gelten zu 80 % dieselben Regeln wie für alle anderen Produkt-Anleitungen auch. Aber auf diesem Gebiet gibt es zusätzliche Empfehlungen, um den Anwendern das Produktverständnis zu erleichtern. Um solche zusätzlichen Empfehlungen haben sich spezielle ISO-Normen verdient gemacht. Das ist schon deswegen recht hilfreich, weil es auf diesem Spezialgebiet zur Zeit nur hoffnungslos veraltete Fachliteratur gibt – also, genau genommen, gar keine. Diese Lücke füllen die ISO-Normen (vgl. Literaturangaben [2], [3], [4]) und Pichlers Seminar „So schreiben wir Software-Dokumentation“ [5]aus.

Projektmanagement für Software-Dokumentation

Zunächst gehen die ISO-Normen davon aus, dass das Schreiben von Software-Dokumentation zu managen ist, wie jedes andere Projekt auch. Deswegen beschreiben sie den Lebenszyklus eines solchen Projekts in 6 Projektphasen (vgl. [3]):

1. Auftrag klären

Dokumentationspolitik

Wie ist die Dokumentationspolitik des Herstellers?

Was genau sind die Gegenstände des Projekts?

Welches Ziel sollen wir erreichen?

2. Planen und Steuern

Den Dokumentationsplan für das Projekt entwerfen

Überwachungssteuerung organisieren

3. Analysieren und entwerfen

Informationen über das Produkt und seine Anwender sammeln.

Informationen über Aufgaben und Informationsbedarf der Anwender sammeln.

Die Dokumentation auf Basis des Bedarfs gestalten.

4. Entwickeln und Kontrollieren

Die (internen) Normen des Unternehmens,

zum Projekt und Produkt für das Entwickeln des Produkts anwenden.

Vorlagendokumente erstellen.

5. Bewerten und aktualisieren

Die Dokumentation mit dem Produkt abgleichen.

6. Herstellen

Die gedruckte Version auf geeigneten Medien vorbereiten.

Redaktionsrichtlinien für Software-Dokumentation

Sehr umfangreiche Abschnitte der ISO 18019 behandeln Redaktionsrichtlinien. Gerade wenn interne und externe Gruppen an einem Projekt zusammen arbeiten, kann die Dokumentation ohne Redaktionsrichtlinie kaum gelingen, weil jeder Projektteilnehmer wahrscheinlich andere Dokumentationsregeln im Kopf hat. Dies sind die Themen, die in Redaktionsrichtlinien für alle Projektteilnehmer verbindlich geregelt sein sollten:

Überblick über Softwarestruktur

Orientierung und Navigation

Struktur von Prozessbeschreibungen

Struktur von Aufgabenbeschreibungen

Felder und Optionen

Namen und Schnittstellenobjekte

Online-Meldungen: Typen, Darstellung, Terminologie

Begriffsdefinitionen

Antworten auf häufig gestellte Fragen (FAQ)

Gestaltung der Online-Dokumentation

Gestaltung der Online-Hilfe

Illustrationen gestalten

Weitere Hilfen für Schreibstil und -techniken (zum Teil nur für Dokumentation in englischer Sprache) finden sich in Style-Guide-Fachbüchern ([6], [7], [8] sowie in Anhang D von [3]). Daraus folgen die wichtigsten Empfehlungen:

Meldungen

Für gleiche Zustände konsistent dieselben Wörter und Begriffe verwenden.

Den Produktentwicklern Hilfe anbieten, für Produktoberfläche, Meldungen und Dokumentation konsistent die richtige Terminologie zu verwenden.

Formulierungen vermeiden, die Anwender tadeln oder Irrtümer begünstigen.

Den Eindruck vermeiden, Soft- oder Hardware könne denken oder fühlen.

Das Wort „bitte“ vermeiden.

Produkt-Glossar, Lexikon, Fachausdrücke

Die Dokumentation soll einfache und den Lesern vertraute Wörter verwenden.

Ein Produkt-Glossar definieren, das gleichermaßen für Software und Dokumentation gilt.

Rechtschreibung nach DUDEN23:2004 prüfen.

Die Begriffe sollen der Sprache der Anwender angehören, nicht der der Entwickler.

Vorherrschende Fehler vermeiden

Auch wenn alle denselben Sprachfehler machen, kommt dabei nichts Richtiges heraus, zum Beispiel: z.B. ohne Leerzeichen dazwischen wird auch durch allgemeine Verwendung nicht richtiger. Auf das in der Typografie gebräuchliche 1/4 oder 1/8 Geviert wollen wir hier in der Softwaredokumentation bewusst verzichten.

Konsistent formulieren

Für gleiche Zustände und Objekte konsistent dieselben Wörter und Begriffe verwenden.

Elegante Abwechslung, die den Satz lediglich interessanter wirken lassen soll, vermeiden.

Wenn für etwas Gleiches verschiedene Begriffe verwendet werden, könnten nicht nur Leser, sondern auch Übersetzer denken, dass etwas Verschiedenes gemeint ist.

Zielgruppenorientiert formulieren

Untersuchen, welche Terminologie in der Arbeitsumgebung der Anwender üblich ist, und diese korrekt verwenden.

Terminologie vermeiden, die nur in der Entwicklung und Technik-Redaktion üblich ist. Im Zweifel eine Zielgruppenanalyse durchführen.

Branchenspezifische Terminologie korrekt verwenden.

Ziel und Ergebnis angeben

Das Ziel regt bei den Anwendern das mentale Modell der Aufgabe an und hilft so, die Instruktionen zu interpretieren und sich Folgeschritte vorstellen zu können.

Die Angabe des Ergebnisses einer Aktion soll Anwendern die Möglichkeit geben, die Richtigkeit ihrer Aktionen zu prüfen.

Instruktionen im Imperativ formulieren

Beispiele:

Enter drücken (oder: Drücken Sie Enter).

Alle Felder markieren und dann SUM eingeben.

Nummerierte Listen für Reihenfolge

Aktionen, die in strikter Reihenfolge durchzuführen sind, als nummerierte Listen anbieten.

Aktionen, die nicht in strikter Reihenfolge durchzuführen sind, als unnummerierte Listen (z. B. mit Blickfangpunkten) anbieten.

Abschnitte und Satzstruktur

Ein Abschnitt soll nicht mehr als genau eine Idee transportieren.

Abschnitte sollen so kurz wie möglich sein.

Wenn für komplexe Zusammenhänge längere Absätze benötigt werden, diese lieber in Listen oder Tabellen umorganisieren.

In der Online-Dokumentation sollen Abschnitte durchschnittlich kürzer sein als in Handbüchern.

Der Übergang von einem Satz zum nächsten soll schlüssig sein, ebenso von einem Absatz zum nächsten.

Komplizierte grammatische Strukturen vermeiden, weil Anwender sie dreimal lesen müssen, ehe sie sie einmal verstanden haben.

Lange Sätze vermeiden (auch, um evtl. Übersetzungen nicht unnötig zu erschweren).

Sätze sollen mit bekannter Information beginnen und von dort aus zu neuen Erkenntnissen führen.

Positiv formulieren

Wenn immer möglich, die Satzkonstruktion positiv formen.

Kein Satz soll mehr als eine Negation enthalten.

Falsches Beispiel:

Sie werden die Suchergebnisse solange nicht sehen, wie sie nicht auf Anzeige geklickt haben.

Richtiges Beispiel:

Um die Suchergebnisse zu sehen, auf Anzeige klicken.

Aktiv statt passiv

Wenn immer möglich, aktiv formulieren.

Falsches Beispiel:

Wenn neue Werte eingegeben werden, müssen Sie die Datei sichern.

Richtiges Beispiel:

Wenn Sie neue Werte eingegeben haben, müssen Sie die Datei sichern.

Gute Gründe für Illustrationen

Illustrationen können die Aufmerksamkeit auf wichtige Informationen lenken. Leser blicken meistens zuerst auf Illustrationen.

Illustrationen eignen sich für:

Prozessbeschreibungen,

Beziehungen,

Hierarchien,

Netze,

Strukturen,

Formen,

Positionen,

Statistiken,

Trends,

Richtungen,

Proportionen,

Wechselbeziehungen,

(Land)Karten aller Art.

Objekt-Bilder helfen Anwendern, Einzelteile, Baugruppen oder das ganze Objekt zu erkennen.

Illustrationen unterstützen das Erinnerungsvermögen.

Illustrationsstile

Überflüssige Information und Detailtreue vermeiden.

Die Wiedergabequalität berücksichtigen. Haarlinien z. B. können im Druck ausbrechen. Mindest-Liniendicke definieren, z. B. 0,5 Punkt.

Die Illustrationstypen konsistent verwenden und gestalten.

Die ganze Illustration soll auf einen Blick zu erfassen sein.

Texte in Illustrationen vermeiden. Referenzziffern verwenden und in der Legende definieren.

Für internationale Zielgruppen keine kulturabhängigen Illustrationen verwenden.

Online-Hilfe

Online-Hilfe dient den Benutzern beim Bearbeiten ihrer Aufgaben mit einer Software-Anwendung. Sie müssen darauf spontan zugreifen können, wenn sich beim Arbeitsablauf unvorhergesehene Hürden aufbauen. Die Online-Hilfe zeigt den Anwendern, wie sie die Hürden schnell und richtig überwinden.

Beispiele für den Nutzen von Online-Hilfen:

Informationen über Befehlseingaben, Tastenkombinationen, Aufgabenabläufe;

detaillierte Erklärungen über Konzepte;

Listen von Optionen;

Beschreibung von Dialogfenstern und wie sie auszufüllen sind.

DIN EN ISO 9241-13 gibt im Rahmen von Benutzerführung nützliche Hinweise für Online-Hilfe zu folgenden Gesichtspunkten:

Systeminitierte Hilfe

Benutzerinitiierte Hilfe

Darstellung der Hilfe-Informationen

Steuerung der Hilfe-Informationen

Kontextfreie Hilfe mit Suchmöglichkeit

Kontextsensitive Hilfe

Software-Dokumentation bewerten

In den Anhängen der ISO-Normen finden sich Checklisten, mit denen man kontrollieren kann, ob die Qualitätskriterien erfüllt wurden, die man zu Beginn des Dokumentationsprojektes definiert hatte. Daraus ergibt sich ggf. Handlungsbedarf für Nachbesserungen

Software-Dokumentation kalkulieren

Verfahrensregeln wie in ISO/IEC 18019

ISO/IEC 15910:1999-12-15 regelt den Dokumentationsprozess mit Analyse, Plan, Entwurf, Revisionen, Herausgabe ebenso wie ISO/IEC 18019, nur dass hier zusätzlich die Aufgabenverteilung zwischen Auftraggeber und Technik-Redaktion geregelt ist. Da bei externen Auftragsbeziehungen immer auch Kosten die zunächst sichtbarste Rolle spielen, seien aus dieser Norm die Kalkulationsmethoden referiert.

Von den Kostenkomponenten zum Projektpreis

Die folgende Tabelle zeigt die Zeiten für ein "typisches" Projekt und geht davon aus, dass der Autor sein Material direkt in einen PC tippt und DTP anwendet.

Arbeitsschritt

Geschätzte Zeit

Lieferumfang bestimmen

16 Stunden je Projekt

Inhalt recherchieren

24 Stunden je Projekt

Dokumentations-Plan schreiben

48 Stunden je Projekt

Dokumenten-Struktur und das Seiten-Layout gestalten

8 Stunden je Ausgabe

Ersten Entwurf schreiben

1 Stunde je Seite

Grafiken entwickeln

5 Stunden je Grafik

Text und Grafiken zusammen stellen

30 Minuten je Seite

Ersten Entwurf auf technische Genauigkeit prüfen (Arbeitgeber)

30 Minuten je Seite

Entwurf und Grafik berichtigen

30 Minuten je Seite

Anwender-Kommentare einarbeiten

30 Minuten je Seite

Grammatik überarbeiten

15 Minuten je Seite

Zweiten Entwurf vorbereiten

15 Minuten je Seite

Zweiten Entwurf prüfen (Auftraggeber)

15 Minuten je Seite

Schlusskorrektur

10 Minuten je Seite

Anwendertest (löst ggf. erneut Handlungsbedarf aus)

15 Minuten je Seite

Druckvorlage montieren

3 Tage

Ordner und Trennblätter bedrucken

5 Tage

Exemplare drucken und zusammen tragen (einfarbig schwarz)

10 Tage

Fazit

Wenn man die Empfehlungen der einschlägigen ISO-Normen befolgt, dann hat man sehr gute Voraussetzungen geschaffen, um Anwendern eine in sich schlüssige sowie kurz und klar formulierte Software-Dokumentation an die Hand zu geben, mit der sie ihre Arbeitsaufgaben richtig schnell lösen können.

Dieser Fachbeitrag soll helfen, Software-Dokumentation neutral zu bewerten. Für tiefergehende Bewertungen ist die Lektüre der ISO-Normen[2], [3], [4] zu empfehlen.

Literatur

[1]

Herwartz, Rachel: Mit lautem Denken zum besseren Handbuch.

Lexware-Programm im Anwendertest.

In: technische kommunikation. 6/2004, S. 38-44, Lübeck

[2]

DIN EN ISO 9241-13:2000-08.

Ergonomische Anforderungen für Bürotätigkeiten mit Bildschirmgeräten, Teil 13: Benutzerführung

[3]

ISO/IEC 18019:2004-01.

Software and system engineering – Guidelines for the design and preparation of user documentation for application software

[4]

ISO/IEC 15910:1999-12. Information technology – Software user documentation process

[5]

Pichler, Wolfram W.: Teilnehmer-Handbuch zum Seminar „So schreiben wir Software-Dokumentation“

mit den Schwerpunkten Handbuch und Online-Hilfe. 2004, Berlin

(Seminar-Auskünfte: www.aronline.de)

[6]

Baumert, Andreas: Gestaltungsrichtlinien – Style Guides planen, erstellen und pflegen.

ISBN 3-9805770-5-8, 1998, Reutlingen, doculine Verlags-GmbH

[7]

The Economist: Style Guide – The best-selling guide to English usage; 7th Edition,

ISBN 1-86197-346-2, 2001, London, Profile Books Ltd.

[8]

Microsoft Manual of Style for Technical Publications. 2004-07, 398

ISBN 0-7356-1746-5

Analysen

Gibt es bei der Software keine Produkt-, Zielgruppen- und Tätigkeitsanalysen als weitere Grundlage der Dokumentation?

Das ist eine sehr gute Frage...

Wolfram Pichler ließ der transline tecNews-Redaktion folgende Antwort zukommen:

"Das ist eine sehr gute Frage – vielen Dank dafür. "Selbstverständlich" sind solche Analysen Grundlage eines jeden Dokumentationsprojekts, also auch in der Softwaredokumentation. Unter der Überschrift "Projektmanagement..." hatte ich das Thema gestreift:

" 3. Analysieren und entwerfen

Informationen über das Produkt und seine Anwender sammeln.

Informationen über Aufgaben und Informationsbedarf der Anwender sammeln.

Die Dokumentation auf Basis des Bedarfs gestalten."

Da nun aber der Ruf nach mehr Details zu diesem Themenkreis laut geworden ist, trage ich dazu bereitwillig noch einige nach – frei nach den zitierten ISO-Normen.

Zur Produktanalyse:

Was ist das Ziel des Produkts? Gibt es Vorläufer? Wann soll das Produkt verfügbar sein?

Muss es lokalisierte Versionen geben? Welche Wartungs- und Updateabsichten gibt es?

Wird die Software international vertrieben, in welche Länder, mit welchen Lokalisierungen?

Für welche Organisationen müssen kundenspezifische Versionen entwickelt werden?

Von diesen Faktoren hängen ab: Zeit- und Kostenpläne, Anwendertests, Stil, Darbietung.

Wird die Dokumentation mit dem Hauptprodukt zusammen verpackt?

Gibt es eine Corporate-Design-Vorschrift für die Verpackung?

Über welche Medien wird das Produkt verteilt?

Welche Versandmethoden werden angewendet?

Ist die gleiche Verpackung wie für frühere oder ähnliche Produkte zu verwenden?

Welchen Copyright-Regeln unterliegt das Produkt, evtl. regional unterschiedlich?

Wie sind Zitate aus fremden Werken zu behandeln?

Wie ist zu verfahren mit Datenschutz, Handelsmarken, Lizenzbedingungen, Plattform-Logos, Urheberrechten, öffentlichen Körperschaften, Garantiebedingungen, Kopierschutz und Schutz sensibler Information?

Kennzeichnung der Software:

Name, Betriebssystem, Ausgabe, Version, Sprache

Ausgabedatum

Produkt-Identnummer

Kennzeichnung der Dokumentation mit Titel und Referenznummer

Produkthersteller oder -vertrieb mit Anschrift, Telefon, Fax, E-Mail- und Web-Adresse

Autor/Redaktion mit Name, Qualifikation, Position

Kontaktdaten

Lizenzangaben mit Lizenznummer, Name des Lizenzinhabers

Urheberrechtsangaben

Garantiebedingungen

Haftung und Anwenderrechte mit Schulungsmöglichkeit, Softwaresupport, Qualitätsangaben, Zugang zum Quellcode

Angabe von Normen, nach denen die Software entwickelt wurde, und Grad der Konformität

Zertifikate

Zur Zielgruppenanalyse:

Eine Liste aller Produkt-Zielgruppen erstellen und dabei folgende Merkmale berücksichtigen:

Erfahrungs- und Ausbildungshintergrund der Anwender,

Sprachen, mit denen die Anwender vertraut sind,

wie die Software benutzt werden wird.

Gruppen von Anwendern zusammenfassen, so dass einzelne Dokumente sich gleichzeitig an mehrere Zielgruppen wenden können.

Zielgruppen lassen sich auch nach ihrem Erfahrungshorizont und der Nutzungshäufigkeit zusammenfassen:

Würde ein Tutorial helfen, den Gebrauch der Software zu erlernen?

Ist die Nutzung nur gelegentlich oder unregelmäßig, was Redundanzen erfordern würde?

Erarbeiten die Anwender sich fortgeschrittene Funktionen?

Bei Verbraucher-Softwarepaketen sind die typischen Arbeitsaufgaben der Anwender zu berücksichtigen und Beispiele aus ihrer Alltagspraxis anzubieten. Bei weiten Bereichen von Ausbildung, Erfahrung und Übung der Anwender soll die Information auch noch die unterste Wissensebene der Anwender abdecken.

Für jeden Anwendertyp ein Zielgruppenprofil schreiben, das alle gesammelten Informationen enthält. Dieses Profil ist ebenso für die Dokumentationsplanung nützlich, wie als Richtlinie für Autoren, Übersetzer und Illustratoren.

Zielgruppenorientiert formulieren:

Untersuchen, welche Terminologie in der Arbeitsumgebung der Anwender üblich ist und diese korrekt verwenden.

Terminologie vermeiden, die nur in der Entwicklung und Technik-Redaktion üblich ist. Im Zweifel eine Zielgruppenanalyse durchführen.

Branchenspezifische Terminologie korrekt verwenden.

Tätigkeitsanalyse:

Anwendern Fragen stellen und sie bei der Arbeit beobachten, um Informationen über ihre Arbeitsgewohnheiten zu sammeln. Falls dies nicht möglich ist, z. B. weil die Software noch in der Entwicklung ist, die Arbeitsweise durch scharfes Nachdenken ermitteln oder andere Quellen benutzen, wie z. B. Anwendungsfall-Entwicklungsdokumente.

Details darüber aufzeichnen, welche Zielgruppe welche Aufgaben erfüllt, am besten in einer Matrix.

Warum und wie häufig wird eine Afgabe erledigt?

Wie werden Anwender die Aufgaben lösen?

In welcher Reihenfolge werden Anwender die Aufgaben bearbeiten?

Welche Voraussetzungen müssen für die Aufgabe erfüllt sein?

Wie fehlertolerant ist die Software beim Bearbeiten der Aufgabe?

Welches Ergebnis ist nach Bearbeitung derAufgabe zu erwarten?

Alle Details einer jeden Aufgabe in einem Aufgabenprofil festhalten.

Aufgabenbeschreibungen beantworten Fragen wie:

"Wie tue ich das?"

"Muss ich das überhaupt tun?"

"Tue ich das Richtige?"

"Warum tue ich das?"

Den Aufgabenbeschreibungen für zusammenhängende oder ähnliche Aufgaben eine gemeinsame Struktur geben und die gleichen Abschnittsüberschriften verwenden. Dabei berücksichtigen:

Aufgabenname, Aufgabenidentifikation, Unterschied zu anderen Aufgaben

detaillierte Voraussetzungen und was danach geschehen sollte

Anfangspunkt mit Angabe der Voraussetzungen und Input

Nummerierte Liste mit Instruktionen in der richtigen Schritt-für-Schritt-Reihenfolge

Endpunkt mit Angabe des Ergebnisses oder wann die Aufgabe beendet ist

Dipl.-Ing Wolfram W. Pichler, Technik-Autor, Süd-West-Berlin"

Software-Dokumentation für Anwender schreiben - Handbücher und Online-Hilfen neutral bewerten