Softwaredokumentation erstellen

Softwaredokumentation ist vielfältig: Aus der Software aufrufbare Online-Hilfen, spezielle Tutorials oder gedruckte Bedienhandbücher sind möglich.

Zur Softwaredokumentation gehören auch die Inhalte auf Displays und Oberflächen von elektronischen Geräten sowie User Interface-Texte auf Benutzeroberflächen.

Online-Hilfen: Software dokumentieren

Um die Benutzer beim Umgang mit der Software optimal zu unterstützen, deckt die Online-Hilfe spezifische Arbeitskontexte ab. Die Online-Hilfe stellt die jeweils benötigten Informationen aufgabenorientiert zur Verfügung, damit offene Fragen ohne großen Suchaufwand gelöst werden können. Der Aufbau der Softwaredokumentation richtet sich nach den Aufgaben, die Anwender lösen müssen. Mit Hilfe-Schaltflächen oder der F1-Taste rufen Benutzer die Online-Hilfe auf.

Die Online-Hilfe zeichnet sich durch eine Reihe von effizienten Merkmalen aus, die sie für Softwaredokumentation besonders geeignet machen.

Merkmale von Softwaredokumentation:

Kontextsensitivität
Die Kontextsensitive Online-Hilfe liefert Informationen zum speziellen Nutzungskontext, in dem sich Benutzer gerade befinden. In der Regel handelt es sich dabei um Beschreibungen einzelner Elemente der Software wie Schaltflächen oder Dialoge. Der Hilfetext ist damit passgenau, allerdings auch sehr spezifisch und kleinteilig.
Modularisierung
Die Online-Hilfe wird topic-orientiert erstellt, d.h. die Inhalte sind in Module aufgeteilt, die jeweils ein in sich abgeschlossenes Thema behandeln. Weitere relevante Themen lassen sich durch Links auf die entsprechenden Topics anzeigen. Damit sollen Benutzer genau die für sie passenden Informationen erhalten. Modularisierung wird nicht nur bei der Erstellung von Softwaredokumentation eingesetzt, sondern generell dann, wenn es um die Wiederverwendung von bestimmten Inhalten geht.
Hypertextualität
Online-Hilfen sind Hypertext-Gebilde, d.h. sie bestehen aus einer netzartigen Struktur von Topics, die durch Links verknüpft sind. Damit unterscheidet sich die Softwaredokumentation grundlegend von linear aufgebauten Dokumenten, die der klassischen Buchstruktur folgen: Die Benutzer können Informationen in beliebiger, selbstgewählter Reihenfolge aufrufen. Hierzu stehen ihnen entsprechende Navigationswerkzeuge zur Verfügung. Auch Medien außerhalb der Online-Hilfe können verlinkt werden und so zum Mehrwert beitragen.
Navigation
Neben den Links gibt es weitere Elemente, die die Navigation in Online-Hilfen unterstützen:
Breadcrumbs: Benutzer erhalten eine Orientierungshilfe, mit der sie den zurückgelegten Weg in der Online-Hilfe nachverfolgen und die aktuelle Position in der Online-Hilfe sehen können
Backtracking: Benutzer können schrittweise zu bereits besuchten Topics zurückgehen
Lesezeichen oder Bookmarks: Benutzer können sich Marken setzen, um für sie relevante Topics leichter wieder auffindbar zu machen
Drop-Down und Embedded Text
Redakteure können Informationen mit Drop Down-Funktionen oder mit Embedded Text erweitern. Mit diesen Funktionalitäten können Benutzer Zusatzinformationen in der Online-Hilfe ein- oder ausklappen. So bestimmen Benutzer selbst, wieviel Informationen sie konsumieren wollen: sich rasch einen Überblick verschaffen oder sich tiefgehend mit einem Thema beschäftigen.
Kommentar- und Feedbackfunktion
Feedback und konstruktive Kommentare helfen Ihnen dabei, den Kontakt zum Benutzer zu halten und ungeahnte schwierige Themen in der Dokumentation ausführlicher zu beschreiben.
Screenshots
Um die Dokumentation möglichst anschaulich zu gestalten, bindet man Screenshots in die Online-Hilfe ein. Dabei gibt es einiges zu beachten.
Screenshots in Softwaredokumentation
Weitere Informationen
Softwaredokumentation

Texte auf der Benutzeroberfläche: User Interface-Texte als Teil der Softwaredokumentation

Inhalte auf Displays von elektronischen Geräten und User Interface-Texte gehören zur Softwaredokumentation und müssen verständlich, konsistent und korrekt sein, um die sichere Bedienung durch die Anwender zu gewährleisten. Entwickler erstellen sie. Manchmal bearbeiten Technische Redakteure sie anschließend. Dabei gibt es Regeln zu beachten.

Anwender lesen User Interface-Texte anders als Fließtext, zum Beispiel in der Online-Hilfe. Sie lesen nicht von links oben nach rechts unten, sondern sie überfliegen das gesamte User Interface und erfassen dabei die Texte und die Schaltflächen. Sie lesen nicht, sie scannen. Ein weiterer Unterschied zum Lesen eines normalen Fließtextes besteht darin, dass Anwender sofort aufhören zu lesen, wenn sie wissen, wie sie ihr Ziel erreichen.

Oft ist sehr wenig Platz auf der Benutzeroberfläche vorhanden. Daher müssen diese Hilfetexte besonders kurz, prägnant und konsistent sein. Konsistente Beschriftungen auf Schaltflächen und anderen Elementen des User Interfaces sind unerlässlich für die Usability.

Meldungstexte, Bestätigungsdialoge sowie Anleitungstexte, die auf dem User Interface angezeigt werden, sind bei Technischen Redakteuren in guten Händen. Sie prüfen, ob sie konsistent und gut verständlich sind. Fehlermeldungen sollten besonders informativ sein. Sie beschreiben nicht nur den Fehler, sondern sie erklären auch, wie Benutzer ihn beheben können. Für User Interface-Texte gilt, was für den gesamten Content eines Unternehmens gilt: Die Terminologie muss stimmen.

Checkliste, die bei der Erstellung von User Interface-Texten Ihrer Softwaredokumentation hilft:

Terminologie beachten. Keine internen Ausdrücke benutzen.
So wenig Wörter wie möglich verwenden
Bei ganzen Sätzen: Keine Passivsätze
Bei Handlungsanleitungen den typischen Aufbau dieser Textsorte umsetzen.
Übersetzungen sind in den Zielsprachen eventuell länger. Extra Platz für Übersetzungen einplanen.
Regeln für Groß- und Kleinschreibung sowie für Interpunktion festlegen. Es ist sinnvoll, diese Regeln im Redaktionsleitfaden festzuhalten.
Informative Fehlermeldungen formulieren. Was ist der Fehler? Wie wird er behoben?

Wir dokumentieren Ihre Software. Als Lieferant und zuverlässiger Dienstleister arbeitet people text mit dem Autorensystem Ihrer Wahl, um Ihre Software zu dokumentieren. Den Erstellungsprozess Ihrer Softwaredokumentation integrieren wir reibungslos in Ihre redaktionellen Prozesse.