Sie suchen auf: {{ keyword }}

Erstellen von klarer Software-Dokumentation (2024)

24.3.22 Ferry Vermeulen Gebrauchsanweisungen

Worauf müssen Sie beim Erstellen einer Software-Dokumentation achten? Lesen Sie hier die 25 Schritte, mit denen wir klare Dokumentationen schreiben.

Inhaltsverzeichnis

#1 Definieren Sie die Anforderungen an die Software-Dokumentation
#2 Bestimmen Sie die Zielgruppe und die Aufgaben der Anwender
#3 Gehen Sie handlungsorientiert vor
#4 Bestimmen Sie die Tools innerhalb des Aufgabenbereichs
#5 Erleichtern Sie die Lösung von Problemen
#6 Sorgen Sie für eine gute Lesbarkeit der Dokumentation, um damit zu arbeiten, daraus zu lernen und zu lokalisieren
#7 Geben Sie Auskunft über den Kontext
#8 Sorgen Sie dafür, dass die Informationen leicht auffindbar sind
#9 Wählen Sie aussagekräftige Überschriften
#10 Verwenden Sie modulare Textbausteine
#11 Formulieren Sie klare Arbeitsschritte
#12 Verwenden Sie aktive Verbformen
#13 Achten Sie auf Konsistenz im Text
#14 Vermeiden Sie umgangssprachliche Ausdrücke
#15 Verwenden Sie einen geeigneten Schreibstil-Leitfaden
#16 Wählen Sie das richtige Ausgabeformat
#17 Gestalten Sie die Informationen möglichst kontextbezogen
#18 Treffen Sie eine gut durchdachte Auswahl der bereitgestellten Informationen
#19 Erstellen Sie eindrucksvolle Illustrationen
#20 Verwenden Sie eine Vorlage
#21 Beurteilen Sie die Anwendbarkeit der Dokumentation
#22 Managen Sie den Inhalt
#23 Organisieren Sie die Übersetzungen
#24 Wenden Sie agile Methoden an
#25 Wählen Sie die Informationsvermittler sorgfältig aus

Merkmale und Vorteile einer guten Software-Dokumentation

Wir verwenden Software von Google, um den schnellsten Weg zum Sportclub zu finden, um etwa nach der Bedeutung des Wortes „Glabella“ zu suchen oder um unser Werbebudget aufzustocken.

Wir setzen Textverarbeitungsprogramme, Buchhaltungs-Software und Grafik-Tools zur Bewältigung aller möglichen Aufgaben ein. Aber auch Prozesse, die wir kaum noch bewusst wahrnehmen, wie zum Beispiel die reibungslose Schaltung der Verkehrsampeln und der Bezahlvorgang am Parkscheinautomat, werden durch Software unterstützt.

Und durch Entwicklungen wie Industrie 4.0, künstliche Intelligenz, Meta-Products, Robotik, Big Data oder das Internet der Dinge sind Software und Hardware heutzutage vollständig integriert.

Hinzu kommt dann auch noch die rasant fortschreitende Entwicklung von Apps.

Zu einer guten Software gehört natürlich eine gute Gebrauchsanweisung.

Daher beschäftigen wir uns Tag für Tag mit der Erstellung von Software-Dokumentationen für eine breite Vielfalt von Kunden und Entwicklern.

Ein Beispiel dafür ist die Online-Hilfe von Madcap Software:

online help

Oder die Anwenderdokumentation des Maschinenherstellers COGNEX:

Cognex

Was versteht man unter Software-Dokumentation?

Die Software-Dokumentation (oder auch Softwareanleitung) umfasst alle Dokumente, die mit einer Computersoftware geliefert werden. Dazu zählen Textmaterialien, Illustrationen und Videoanleitungen.

In der Software-Dokumentation werden Informationen zur korrekten Nutzung eines Programms oder einer Dienstleistung bereitgestellt.

Es werden verschiedene Arten von Software-Dokumentation unterschieden ‒ je nach Zielgruppe, für die sie erstellt wird. Beispiele dafür sind Technische Dokumentationen und Dokumentationen für die Endanwender.

  • Technische Dokumentationen umfassen die Dokumentation des Softwarecodes, der Algorithmen und Programmierschnittstellen. Diese Art von Software-Dokumentation wird für Anwender mit entsprechenden technischen Kenntnissen verfasst, wie etwa Softwareentwickler.
  • Eine Anwenderdokumentation beschreibt wiederum die Aufgaben der Endanwender. Sie umfasst Informationen, die diese Anwender benötigen, um ein bestimmtes Ziel zu erreichen.

Software-Dokumentation wird oftmals in Form einer Onlinehilfe, als sogenannte „Context-sensitive Help“, als „On-Device-Information“ oder in Form einer PDF-Datei bereitgestellt, die zum Download zur Verfügung steht.

Erstellen von Software-Dokumentation

Für das Erstellen von anwenderfreundlicher, nützlicher und gut gegliederter Software-Dokumentation gilt es, bestimmte Kriterien zu erfüllen. Darüber hinaus sollte ein strukturiertes Verfahren befolgt werden, das oft auf den agilen Methoden der Softwareentwickler basiert.

Wofür wird eine gute Software-Dokumentation benötigt?

Die korrekte Bereitstellung nützlicher, gut strukturierter Anwenderinformationen macht sich in Hinblick auf die Investitionen, die im Zuge der Entwicklung eines Softwareprodukts getätigt werden, eindeutig bezahlt. Dank einer guten Software-Dokumentation kann der Aufwand für Schulungen und Einweisungen reduziert werden. Sie bietet gezielt Hilfe bei der Lösung von Aufgaben, sodass die Anwender die Software rasch produktiv nutzen können. Eine gute Software-Dokumentation sorgt somit für einen guten Ruf des Produkts, des entsprechenden Herstellers und des Softwareanbieters.

Das Erstellen einer guten Software-Dokumentation beschränkt sich nicht nur auf das Verfassen von Texten. Auch die Kommunikation mit den Softwareentwicklern, das Verständnis der Funktionen und der Aufgaben der Anwender, die Organisation und Strukturierung der Informationen, das Managen des Inhalts, die Veröffentlichung sowie die kontinuierliche Pflege der Inhalte sind unerlässliche Faktoren.
Nachstehend werden einige wichtige Ausgangskriterien beschrieben, die bei der Entwicklung einer guten Software-Dokumentation berücksichtigt werden sollten.

#1 Definieren Sie die Anforderungen an die Software-Dokumentation

Bevor mit der Erstellung der Software-Dokumentation begonnen wird, empfiehlt es sich, einen Projektplan zu erstellen. In diesem Projektplan werden die Anforderungen an das Projekt festgelegt.

Folgende Elemente werden im Projektplan beschrieben:

  • Informationsziele: Was muss damit erreicht werden? Welche Informationen müssen übermittelt werden? Was sind die Anforderungen an die Qualität und die Ausbildungsziele? Welche Anforderungen bestehen in Bezug auf die Wirksamkeit und Effektivität der Informationen? Wie können die Informationen dabei helfen, die Unternehmensziele zu erreichen?
  • Projektreichweite: Für welche Software wird die Dokumentation entwickelt? Wie sieht der weitere Plan aus? Was sind die Prioritäten?
  • Anwenderprofile: Wer sind die Anwender der Software? Durch welche Besonderheiten zeichnen sie sich aus? Welche Bedürfnisse haben die Anwender? Über welche Nutzungsrechte verfügen sie? Was sind die wichtigsten Aufgaben und Szenarien der Anwender? In welcher Umgebung arbeiten sie? Welche weiteren Anforderungen bestehen bezüglich der Anwender?
  • Übersicht des Inhalts, der erstellt werden muss: Welche Themenfelder müssen ausgearbeitet werden? Welcher Inhalt ist für die Kunden und eventuelle andere Anwender notwendig? Besteht ein Unterschied zwischen Konzepten, Aufgaben und Referenzen?
  • Anforderungen an die Zugänglichkeit der Informationen: Über welche Medien müssen die Informationen zur Verfügung gestellt werden: online, in ausgedruckter Form oder als Video? Sind die Informationen für jeden zugänglich? Werden Richtlinien des W3C (World Wide Web Consortium) und Ergonomiestandards berücksichtigt?
  • Anforderungen in Bezug auf Übersetzung und Lokalisierung: In welchen Ländern wird die Software genutzt? In welche Sprachen muss sie übersetzt werden? Welche Teile müssen lokalisiert werden?
  • Teillieferungen und Endlieferung: Was sind die wichtigsten Meilensteine? Wird die Dokumentation in ausgedruckter oder elektronischer Form übergeben?
  • Anforderungen an die zu verwendenden Tools (CMS/CCMS): Wie werden die Informationen behandelt? Wer muss mit dem Managementsystem arbeiten? Wie werden die Informationen ausgetauscht? Wie gehen wir mit Updates, neuen Versionen und Anpassungen der Benutzeroberfläche um? Ist DITA XML erforderlich?
  • Strategie in Bezug auf die Wiederverwendung der Informationen: Wird ein CMS verwendet? Wird ein Übersetzungsspeicher (also ein Translation Memory oder TM) verwendet? Wird ein globales Projekt angelegt?
  • Risikobeurteilung: Welche Anforderungen bestehen in Bezug auf die sichere Nutzung und Compliance?
  • Projektplanung: Wann muss das Projekt abgeschlossen sein? Was sind die wichtigsten Meilensteine? Müssen agile Methoden angewendet werden?
  • Einschätzung der Projektgröße: Wie viele Stunden werden benötigt?
  • Einschätzung des Projektbudgets: Wie groß ist das geschätzte Budget? Welche Abhängigkeiten bestehen?
  • Teammitglieder und Beteiligte: Wer sind die involvierten Personen? Wer sind deren Verantwortliche?
  • Projektrevisoren und Personen, die den Inhalt genehmigen müssen: Wer ist für die Revisionen zuständig? Wie läuft der Revisionsprozess ab? Wer ist für die Genehmigung des Inhalts verantwortlich? Wie werden die Informationen für die Anwender zusammengetragen?
  • Anforderungen an das Design, das Marketing und weitere Erfordernisse: Welche Anforderungen bestehen seitens weiterer Beteiligter? Welche Anforderungen werden an das Marketing und das Design gestellt?

....
LADEN SIE SICH UNSERE VORLAGE FÜR DEN PROJEKTPLAN HERUNTER (ENGLISH)

#2 Bestimmen Sie die Zielgruppe und die Aufgaben der Anwender, um den Informationsbedarf zu decken

Softwareanwender haben einen Informationsbedarf, der durch die Aufgaben definiert wird, die sie ausführen müssen. Aus diesem Grund ist es wichtig, den Bedarf der Anwender zu kennen und entsprechend festzulegen. Als Teil der Entwicklung einer Bedarfsanalyse muss Folgendes definiert werden:

  • das Anwenderprofil,
  • die Anwenderumgebung,
  • der Anwendungsfall und das Benutzerszenario,
  • die Anwender- und Aufgabenanalyse.

Nach dieser Analyse kann eine Liste mit Themenbereichen erstellt werden, die eine Übersicht der wichtigsten auszuarbeitenden Aufgaben bietet.

Obwohl es unwahrscheinlich ist, dass alle Aufgaben bereits zu Projektbeginn genau definiert sind, kann eine vorläufige Liste der wichtigsten Aufgaben bei der Festlegung des Projektumfangs und der Einschätzung der notwendigen Personal-, Zeit- und Budgetressourcen hilfreich sein.

Topic

#3 Gehen Sie handlungsorientiert vor, sodass die Anwender bei der Erfüllung ihrer Aufgaben entsprechend unterstützt werden

Anwender nutzen die Software-Dokumentation, da sie eine bestimmte Aufgabe mit der Software ausführen oder ein Problem lösen wollen. Oftmals versucht die Software-Industrie, ihr Produkt als eine intuitive Schnittstelle zu verkaufen, für die keine Anwenderunterstützung benötigt wird. Eine Untersuchung ergab allerdings, dass Anwender immer die eine oder andere Form der Unterstützung benötigen.

Um ihre Ziele zu erreichen, möchten Anwender in der Lage sein, Handlungen so schnell wie möglich auszuführen. Die Bereitstellung von Informationen, um sie dabei zu unterstützen, wird als anwenderorientierte Vorgehensweise bezeichnet. Dies ist Grundprinzip der Minimalisierung in der technischen Kommunikation sowie das erste und wichtigste Konzept der Minimalisierung.

Conditions

Das Nummerieren der Handlungsschritte ist ein Beispiel für eine anwenderorientierte Vorgehensweise.

#4 Bestimmen Sie die Tools innerhalb des Aufgabenbereichs

Verschiedene Gruppen von Anwendern haben auch unterschiedliche Bedürfnisse. Ein Lehrer hat mit Microsoft Word andere Aufgaben zu bewältigen als ein Forscher, und ein Mitarbeiter aus dem Finanzwesen nutzt ein CRM-Paket zu anderen Zwecken als ein Manager. Daher ist es wichtig, bei der Erklärung einer bestimmten Software- oder Anwenderaufgabe stets die Arbeit und die Zielsetzung der Person, die die Dokumentation zu Rate zieht, zu berücksichtigen.

Bei einigen Ansätzen wird lediglich die reine Funktionalität der Software erklärt. Es geht allerdings darum, die Funktionalität in Bezug auf die Arbeit einer bestimmten Person zu erklären. Erst dann können Anwender die Funktion der Software besser verstehen und diese bei der Ausführung ihrer Aufgaben wirksamer und effektiver einsetzen.

So nutzt ein High-Ticket-Coach Facebook Ads auf eine andere Weise…

FB

...als ein Spezialist für E-Commerce.

FB tutorial

#5 Erleichtern Sie die Fehlererkennung und die Lösung von Problemen, um dem Anwender Ärger zu ersparen

Softwareanwendern können Fehler unterlaufen oder es kann vorkommen, dass ein bestimmter Handlungsschritt nicht zum gewünschten Ergebnis führt. Fehler sind menschlich und kein einziges Produkt kann diese vollständig vermeiden. Untersuchungen zufolge *[1] verbringen Anwender im Durchschnitt 25% bis 50% ihrer Zeit mit dem Korrigieren von Fehlern. Akzeptieren Sie daher die Tatsache, dass es unweigerlich zu Fehlern kommen wird und unterstützen Sie die Anwender bei der Behebung häufig auftretender Fehler.

Beispiel für eine Fehlerbehebung unmittelbar nach der Anweisung

#6 Sorgen Sie für eine gute Lesbarkeit der Dokumentation, um damit zu arbeiten, daraus zu lernen und zu lokalisieren


Manchmal konsultieren Anwender die Software-Dokumentation, um sich mit ihr näher zu beschäftigen, in einigen Fällen aber auch, um zielgerichtet Informationen zu finden. Meistens wird eine Software-Dokumentation jedoch dazu genutzt, um Probleme zu lösen oder um Hilfe bei der Ausführung von Aufgaben zu erhalten.

Eine Anleitung sollte diese Lesestrategien in der einen oder anderen Form unterstützen. Durch den Verweis auf einen Referenztext oder die Bereitstellung weiterer Informationen am Ende eines Prozesses wird der Lernprozess des Anwenders angeregt.

Software-Dokumentationen

In diesem Beispiel wird der Anwender zu einem weiteren Lernprozess angeregt.

#7 Geben Sie ausreichende Auskunft über den Kontext, damit die Anweisungen verständlich sind

Manchmal ist es notwendig, den Anwendern kontextbezogene Informationen zu geben, bevor ein bestimmtes Verfahren durchgeführt werden kann.

Kontextbezogene Informationen können folgende Funktionen haben:

  • sie können darauf hinweisen, welche Kenntnisse und Hintergründe der Anwender benötigt, um die Anweisungen zu verstehen;
  • sie können darauf hinweisen, welche allgemeinen Ausgangskriterien für das Verfahren bestehen und was damit erreicht werden soll;
  • sie können darauf hinweisen, unter welchen Voraussetzungen die Anweisungen verwendet werden und unter welchen Voraussetzungen nicht;
  • sie können eine Übersicht des Inhalts der Anweisungen bieten.

kontextspezifischen Hintergrundinformationen

In diesem Verfahren sind die Anweisungen nach den kontextspezifischen Hintergrundinformationen ausgerichtet.

#8 Sorgen Sie dafür, dass die Anwender problemlos bestimmte Informationen finden können

Gebrauchsanleitungen sollten einen einfachen Zugang zu Informationen ermöglichen, beispielsweise durch ein Inhaltsverzeichnis, einen Index und andere Suchoptionen.

Solche Such- und Navigationselemente zeigen die Textstelle an, die Anwender von ihrem aktuellen Standort aus aufrufen können, z. B. den Themennamen oder die Seitennummer.

MadCap Flare

Onlinehilfe mit einer Suchfunktion und einem Inhaltsverzeichnis

#9 Wählen Sie aussagekräftige Überschriften und helfen Sie den Anwendern dabei, die entsprechenden Informationen zu finden

Es ist wichtig, Überschriften sorgfältig auszuwählen. Ein konsistenter Stil, ein ansprechendes Layout und eine gute Formulierung sorgen dafür, dass die Anwender die gesuchten Informationen auch problemlos finden.

Die Überschriften sind im Inhaltsverzeichnis und in der Menüstruktur aufgeführt. Leser konsultieren das Inhaltsverzeichnis bzw. das Menü, um so schnell wie möglich zu dem Bereich zu gelangen, der die gesuchten Informationen enthält. Ein eindeutig formulierter Name, der den Eindruck erweckt, dass die gewünschten Informationen innerhalb der Thematik zu finden sind, ist sehr wichtig. Sorgen Sie daher für aussagekräftige Überschriften. Beispielsweise ist die Überschrift Wie backe ich Pfannkuchen? wesentlich anwenderorientierter als der Titel Funktionen des MagicMix2000.

#10 Verwenden Sie modulare Textbausteine

In der Welt der technischen Dokumentation gilt eine themenspezifische Schreibweise als der Standard schlechthin. Bei der themenspezifischen Schreibweise handelt es sich um ein modulares Verfahren zum Erstellen von Inhalten, wobei der Inhalt um bestimmte Themen herum strukturiert ist, die in einem unterschiedlichen Kontext wiederverwendet werden können.

Einem Inhaltsmanagementsystem (CMS) oder einem Komponenten-Inhaltsmanagementsystem (CCMS) liegt eine modulare Struktur zugrunde. Obwohl die modulare Dokumentation nicht notwendigerweise auf XML basieren muss, ist dies trotzdem zumeist der Fall. Standards, die XML nutzen, sind unter anderem DITA und S1000D.

Die Vorteile des Verwaltens von Inhalten auf Komponentenebene sind eine höhere Konsistenz und Genauigkeit, geringere Wartungskosten, geringere Übersetzungskosten und eine entsprechende Nachverfolgbarkeit.

#11 Formulieren Sie in den Anweisungen klare Arbeitsschritte

Ein Beispiel:

Um Deutsch als Ihre Standardsprache auszuwählen:

  1. Gehen Sie auf Datei > Deutsch.
  2. Wählen Sie Deutsch.

...ist viel anwenderfreundlicher als…

Um Deutsch als Standardsprache einzustellen, wählen Sie Deutsch aus, indem Sie im Menü Datei auf Sprache klicken.

Anweisungen erteilen Sie am besten in Form nummerierter Arbeitsschritte. Eine Reihe aufeinanderfolgender Arbeitsschritte beschreibt das Verfahren, das für eine bestimmte Aufgabe durchlaufen werden muss. Eine Serie von Schritten verfolgt ein eindeutiges Ziel, das jeweils auf die Aufgabe ausgerichtet und relevant sein muss.

Sorgen Sie dafür, dass es sich dabei um kurze Schritte handelt. Einfache Sätze, die nur eine einzige Anweisung oder in bestimmten Situationen eine kleine Anzahl eng verwandter Anweisungen enthalten, eignen sich am besten. Am Ende des Schrittes muss eine Aufgabe abgeschlossen sein. In eine Sackgasse zu gelangen, ist nicht im Sinne des Erfinders. Sorgen Sie also dafür, dass der Anwender nach dem Durchlaufen der Schritte das Problem gelöst hat.

Standard Methode

#12 Verwenden Sie aktive Verbformen und Substantive

Mit der Verwendung der aktiven Form werden Anweisungen deutlicher, kürzer und direkter formuliert. Verfassen Sie Anweisungen in der Gegenwart und verwenden Sie dabei starke Verben. Anweisungen, die in der aktiven Form verfasst werden, sind einfacher zu lesen und zu verstehen, da das Subjekt und das Verb immer klar erkennbar sind.

Der Satz „Schließen Sie eine Tastatur an einem USB-Port des externen Geräts an.“ ist deutlicher als „An einem USB-Port des externen Geräts muss eine Tastatur angeschlossen werden.“.

Im ersten Satz ist „anschließen“ das aktive Verb. „Tastatur“, „USB-Port“ und „externes Gerät“ sind jeweils Subjekte. Der zweite Satz wurde hingegen in der Passivform verfasst. In der Aktivform ist wesentlich deutlicher, dass der Leser derjenige ist, der die beschriebene Handlung auszuführen hat. 

#13 Achten Sie auf Konsistenz im Text

Es ist besonders wichtig, Bezeichnungen, Produktelemente (wie etwa Tasten, Fenster etc.) und Einheiten in konsistenter Form zu verwenden. Dadurch werden Doppeldeutigkeiten verhindert und dem Anwender Verwirrung und Ärger erspart.

Das vorhandene Material ist nicht immer deutlich: oft fehlt es an Struktur, Konsistenz oder klareren Anweisungen. Es ist Aufgabe des technischen Verfassers, die Anwenderinformationen in einer einheitlichen Form zu vermitteln. Dies ist unter anderem durch die konsistente Nutzung der Terminologie möglich.

Zudem ist es wichtig, dass die verschiedenen Informationstypen, wie z.B. Warnungen, Handlungsschritte, Fehlererkennung und Tipps, eine konsistente Form haben und immer in der gleichen Weise präsentiert werden. Eine konsistente Form für verschiedene Informationstypen sorgt dafür, dass der Leser sie bewusst oder unbewusst wiedererkennt und mit der Funktion dieses Informationstyps verbindet.

Im folgenden Beispiel einer Software-Dokumentation bilden die Überschrift, die Anweisungen, Produktelemente und Hinweisfelder jeweils Informationstypen, die in der gesamten Software-Dokumentation konsistent gestaltet sind.

Create a Project

#14 Vermeiden Sie Fachjargon

Software-Dokumentation sollte zielgruppengerecht geschrieben sein und möglichst wenig Fachjargon enthalten. Oftmals werden Produktinformationen von Subject Matter Experts (SMEs) zur Verfügung gestellt, also beispielsweise von Softwareentwicklern. Die meisten Entwickler konzentrieren sich lieber darauf, bestimmte Dinge zu erledigen und Ergebnisse zu erzielen. Darüber zu schreiben ist hingegen oft nicht ihre Lieblingsbeschäftigung.

Oft verwenden sie dabei auch viele Fachbegriffe. Als technischer Verfasser ist es wichtig, die richtigen Fragen zur Bedeutung bestimmter Begriffe zu stellen und sich dafür zu entscheiden, welche Informationen in der Software-Dokumentation enthalten sein müssen, damit sie für den letztendlichen Anwender verständlich sind.

#15 Verwenden Sie einen geeigneten Schreibstil-Leitfaden für konsistente Anweisungen

Ein Schreibstil-Leitfaden enthält eine Reihe von Standards und Regeln für das Schreiben und das Behandeln von Inhalten. Ein Schreibstil-Leitfaden für technische Texte definiert den Stil, der in der technischen Kommunikation zu verwenden ist, so wie dies in Anleitungen für Anwender und bei der Onlinehilfe der Fall ist. Ein Schreibstil-Leitfaden ist zudem dabei behilflich, Texte in einer deutlichen Form zu schreiben und einen konsistenten Ton und Stil zu wahren.

Ein Schreibstil-Leitfaden beschreibt beispielsweise, wie mit Abkürzungen, Überschriften, Präpositionen, der Nummerierung von Abbildungen, Illustrationen, Abmessungen, Einheiten, der Interpunktion, Definitionen, Querverweisen, Substantiven, Einfügungen, Aufzählungen, Tabellen usw. umgegangen werden muss. Ein Schreibstil-Leitfaden regt dazu an, alle Details sorgfältig abzuwägen, und er zwingt den Autor dazu, sich jeden einzelnen Satz noch einmal genau anzuschauen. Ein Schreibstil-Leitfaden verbessert dadurch die Verständlichkeit der Software-Dokumentation.

Wir haben unseren eigenen Schreibstil-Leitfaden entwickelt.

Style guide

In diesem Leitfaden ist alles bis ins Detail festgelegt.

ToC

Jedes Thema aus dem Schreibstil-Leitfaden besteht aus einer Reihe von Schreibregeln.

#16 Wählen Sie das richtige Ausgabeformat (Druck, online)

Anwender möchten zu dem Zeitpunkt auf Informationen zugreifen können, zu dem sie diese benötigen. Für eine Desktopsoftware oder eine App ist eine PDF-Datei oder eine ausgedruckte Anleitung allerdings oft nicht ausreichend. On-Screen- oder On-Device-Informationen sind hier klar von Vorteil und sie sollten möglichst kontextbezogen sein.

Ein zusätzlicher Vorteil eines elektronischen Mediums besteht darin, dass die Informationen problemlos aktualisiert und durchsucht werden können. Durch die sorgfältige Auswahl des zu verwendenden technischen Autorenwerkzeugs oder CMS können aus demselben Inhalt sowohl Online- als auch Druckversionen der Software-Dokumentation erstellt werden.

Print und HTML Anleitungen

#17 Gestalten Sie die Informationen möglichst kontextbezogen

Kontextbezogene Hilfe ist eine Form der Online-Hilfe, die von einem bestimmten Punkt im Software-Status aufrufbar ist. Kontextbezogene Hilfe bietet Unterstützung für spezielle Situationen, die mit diesem Status im Zusammenhang stehen.

Kontextbezogene Hilfe muss ‒ im Gegensatz zu allgemeiner Online-Hilfe oder Online-Anleitungen ‒ nicht komplett zugänglich sein, um sie lesen zu können. Bei jedem Thema wird ein Status, eine Situation oder ein Merkmal der Software detailliert beschrieben.

Die Themen, die wir in unserem CMS entwickeln, sind XML- oder HTML-Dateien, die mit jeder Software als kontextbezogene Hilfe integriert werden können.

#18 Treffen Sie eine gut durchdachte Auswahl der bereitgestellten Informationen: Passen Sie den Umfang der Informationen an die Bedürfnisse des Anwenders an

Manchmal benötigt der Nutzer nicht sofort alle Informationen oder bestimmte Informationen sind nicht relevant. Ein unerfahrener Anwender benötigt oft mehr Informationen als ein geübter Anwender. Sie können dann bestimmte Informationsteile ausblenden und bei Bedarf anzeigen lassen. Sie lassen den Anwender entscheiden, ob er etwas benötigt und verhindern dadurch eine Informationsflut.

Im folgenden Beispiel einer Software-Dokumentation haben wir uns entschieden, einen Teil des Inhaltsverzeichnisses zu verbergen.

In diesem Beispiel werden die Informationen für verschiedene Anwenderszenarien ausgeblendet, wobei der Anwender das für ihn relevante Szenarium auswählt.

#19 Erstellen Sie eindrucksvolle Illustrationen

Illustrationen können aus Linienzeichnungen, Fotos, Screenshots, Symbolen, Tabellen, Grafiken und Infografiken bestehen. Screenshots, Videos und GIF-Animationen können in der Software-Dokumentation einen Überblick über Funktionen bieten, den Text verstärken, Handlungsschritte veranschaulichen oder das Ergebnis einer bestimmten Handlung präsentieren.

#20 Verwenden Sie eine Software-Dokumentations-Vorlage und achten Sie auf ein gutes Design
Ungeachtet dessen, dass in puncto Design nahezu alles möglich ist, wirkt es sich positiv aus, eine Vorlage für die Software-Dokumentation zu verwenden.

Wir haben unter anderem folgende Software-Dokumentations-Vorlagen zur Verfügung:

#21 Beurteilen Sie die Anwendbarkeit der Dokumentation

Selbst erfahrene technische Autoren haben nicht immer eine klare Vorstellung davon, welche Probleme sich bei der Nutzung ihrer Dokumentation ergeben könnten. Der beste Weg, um herauszufinden, mit welchen Fehlern die Anwender konfrontiert werden, ist die Durchführung einer Anwendbarkeitsbeurteilung. Sammeln Sie Benutzerfeedbacks und aktualisieren Sie die Dokumentation regelmäßig.

#22 Managen Sie den Inhalt

Wir haben zuvor bereits über den modularen Aufbau der Information gesprochen sowie darüber, dass ein Inhaltsmanagementsystem (CMS) dabei behilflich sein kann. Beim CMS handelt es sich um ein Softwaresystem, welches die Erfassung, Erstellung, Verwaltung und Veröffentlichung von Informationen automatisiert. Inhalt, Gestaltung und Struktur können mit einem Inhaltsmanagementsystem getrennt gehalten werden. So ist das CMS in der Lage, die gewünschten Inhalte aus einer einzelnen Quelle in beliebiger Form zu veröffentlichen. Die Inhalte können wiederverwendet werden, da sie separat verfügbar sind. Dies ermöglicht eine effiziente Nutzung von Informationen und spart Kosten.

Die Vorteile von Inhaltsmanagementsystemen bestehen darin, verschiedene Ausgabeformate mit dem gleichen Inhalt (Druck und online) veröffentlichen und den Inhalt maximal wiederverwenden zu können, sowie in einer mehrsprachigen Integration und einer effizienteren Zusammenstellung neuer Dokumente.

#23 Organisieren Sie die Übersetzungen

Wenn die Software-Dokumentation in mehrere Sprachen übersetzt werden muss, kann auch hier die Verwendung eines CMS oder CCMS von großem Vorteil sein. Die meisten dieser Tools basieren auf Industriestandards, wie beispielsweise XLIFF und TMX. Übersetzungen werden in einem sogenannten Translation Memory verwaltet. Nur diejenigen Teile, die noch nicht übersetzt wurden, werden an ein Übersetzungsbüro weitergeleitet.

#24 Wenden Sie agile Methoden an, die an den Softwareentwicklungsprozess anschließen

Bei der Softwareentwicklung kommen oft agile Entwicklungsmethoden zum Einsatz. Diese Lösungen sind auf die schnelle und häufige Lieferung hochwertiger Software ausgerichtet und umfassen häufig eine kurzfristige Detailplanung.

Obwohl agile Entwicklungsmethoden oft eine geringere Lebenszyklusdokumentation nahelegen, erwarten die Anwender eines Softwareprodukts, dass die Software von Qualitätsinformationen begleitet wird. Denn obwohl das Endergebnis bei der Entwicklung der Software-Dokumentationen das gleiche ist, gestaltet sich die Methode in einer agilen Umgebung wesentlich anders.

Agile Entwicklungsmethoden durchlaufen meist kurze, iterative Entwicklungszyklen auf der Grundlage von Kundenspezifikationen und Feedbacks. Entwickler der Software-Dokumentation müssen über agile Verfahren und Methoden Bescheid wissen, die innerhalb einer Organisation verwendet werden, um daran anschließen zu können.

Wie Sie Normen anwenden für Software-Dokumentation (inkl. Normen für Agile Methoden), hören Sie in unserem Podcast:

#25 Wählen Sie Ihre Informationsvermittler sorgfältig aus

Information für Anwender werden oft als etwas betrachtet, das nach der Implementierung des Systems noch erledigt werden muss. Für die Bereitstellung qualitativ hochwertiger Informationen, sollte die Entwicklung der Software-Dokumentation jedoch als integraler Bestandteil der Software selbst betrachtet werden. Die Entwicklung qualitativ hochwertiger Informationen erfordert eine genaue Planung. Oft beschäftigt sich in einem Unternehmen ein spezielles Team ‒ das Dokumentationsteam ‒ mit der Redaktion technischer Texte.

Eine andere Option ist das Outsourcing. Viele Organisationen entscheiden sich dafür, das Verfassen der Dokumentation auszulagern. Beim Outsourcing dieser Aufgabe muss dafür gesorgt werden, dass die Anforderungen an das Projekt klar sind, indem ein Projektplan erstellt wird. Dies kann oft gemeinsam mit einem möglichen Partner erfolgen. Der Projektplan beschreibt unter anderem die Anforderungen an die Planung, die Einsetzbarkeit, die Sicherheit, die Übersetzungen, die Qualität, die Standards usw. Wählen Sie einen Informationsanbieter aus, der die Anforderungen des Projektplans am besten erfüllen kann.

Tools zum Erstellen einer Software-Dokumentation

Es gibt verschiedene gute Softwarepakete und *Tools, um eine Online-Hilfe und eine weitere Software-Dokumentation zu erstellen.

Wir arbeiten beispielsweise mit MadCap Flare, Author-it, SCHEMA ST4 und Adobe Framemaker. Weitere Tools sind Fischer, Paligo, easyDITA, DITAToo etc.

Haben wir Sie dafür begeistern können, Ihre Onlinehilfe oder Software-Dokumentation erstellen zu lassen? Dann nehmen Sie gleich Kontakt mit uns auf!

KONTAKTIEREN SIE UNS

   

Ferry Vermeulen ist Experte für technische Kommunikation und Geschäftsführer von INSTRKTIV GmbH. Ferry hat es sich zur Aufgabe gemacht, digitale Benutzeranleitungen für alle Produkte der Welt zu erstellen. Hören Sie sich den INSTRKTIV-Podcast auf Spotify an oder lesen Sie einen seiner letzten Blogartikel

Xing I Spotify I YouTube I Facebook I Twitter