In der Technischen Redaktion gibt es klare Vorgaben hinsichtlich rechtlicher und normativer Anforderungen an die Informationsprodukte für Maschinen, Anlagen oder Medizinprodukte. Anders ist das bei Anwendungssoftware, also denjenigen digitalen Produkten, die nicht als Bestandteil einer Maschine oder eines Medizinproduktes auf demjenigen betrieben werden. Bei digitalen Systemen, die auf PCs laufen, gibt es weitaus weniger Regulierung, da keine unmittelbaren Gefahren für Leib und Leben vorhanden sind.

Auch wenn die wichtigste Norm in der Softwaredokumentation die ISO/IEC/IEEE 26514:2022 erst kürzlich überarbeitet wurde und viele grundlegende Informationen für gute und moderne Softwaredokumentation bereithält, handelt es sich am Ende des Tages trotzdem „nur“ um eine Norm und damit erstmal nur um eine Empfehlung.

Die dadurch gegebenen Freiheiten in der Softwaredokumentation haben durchwachsene Qualitätsstandards für Informationsprodukte zu komplexen Softwaresystemen zur Folge. So ganz ohne Regeln geht’s also nicht. Wir haben dir daher 10 wichtige Tipps für den Erfolg deiner Softwaredokumentation hier zusammengetragen.

Tipp 1: Erstelle einen Dokumentationsplan

Ohne gut durchdachtes Konzept, saubere Planung, Abstimmung mit dem Auftraggeber und vor allem Wissen über die Zielgruppe kannst du keine qualitativ gute Softwareanleitung erstellen und versinkst früher oder später im Chaos. Setze daher auf einen guten Dokumentationsplan. Folgendes sollte dieser in jedem Fall enthalten:

  • Wer sind die Stakeholder?
  • Wer sind die Zielgruppen?
  • Welchen Informationsbedarf haben die Zielgruppen?
  • Welche Inhaltsstruktur wird für die Informationsprodukte benötigt?
  • Wie sieht die Informationsarchitektur aus?
  • In welcher Produktlebensphase wird das Informationsprodukt benötigt?
  • Wer erstellt das Informationsprodukt?
  • Wie ist der Projektablaufplan bis zum fertigen Produkt?
  • Wer führt das Review in erster und zweiter Instanz durch?
  • Wie wird das Produkt publiziert?
    • In welche Medien, durch wen, in Abstimmung mit wem?
    • Wer wird über die Publikation in Kenntnis gesetzt?
  • Checkliste zur Durchführungsstatistik dieser Punkte
    • Wer hat was und wann erledigt? (Ticketingsysteme wie Jira/Trello o.ä. bieten hierbei massive Vorteile)

Tipp 2: Versioniere deine Inhalte

Überlege dir vorab ein System zur Versionierung von Dateien und vermittle dein Versionierungssystem an alle Projektbeteiligten. Wenn du kein Redaktionssystem im Einsatz hast, welches diese Funktion beinhaltet, gibt es „Low-Budget“-Alternativen wie GitHub oder Subversion (SVN). Auch OneDrive, Dropbox oder OwnCloud lassen sich gut für eine einfache Versionierung nutzen. Auch Help Authoring Tools wie z.B. MadCap Flare lassen sich gut an Versionsverwaltungssysteme anbinden und ermöglichen eine Versionshistorie für deine Inhalte.

Tipp 3: Erarbeite in jedem Fall ein Metadatenkonzept

Metadaten machen deine Informationen „smart“ oder „intelligent“. Ein durchdachtes Metadatenkonzept hilft dabei die passende Informationseinheit zur richtigen Zeit, am richtigen Ort in der richtigen Menge bereitzustellen. Das reicht von einzelnen Microcopy-Elementen (Texte auf der Benutzungsoberfläche) bis hin zu ausgeklügelten Facetten-Filtern in der Online-Hilfe. Erstklassige Suchergebnisse und damit schnelle Auffindbarkeit der richtigen Informationen sind ein Schlüssel für positive Erlebnisse mit deinen Informationsprodukten und damit letztlich auch im Umgang mit dem beschriebenen Produkt. Natürlich setzt dies voraus, dass du deine Informationen bereits in einem System erfasst, welches das Auszeichnen der Informationen mit Metadaten ermöglicht. Womit wir zu Tipp 4 kommen.

Tipp 4: Erfasse deine Informationen in einem strukturierten System

Wenn du deine Daten noch in einem System schreibst, welches die Informationen unstrukturiert erfasst, solltest du spätestens jetzt darüber nachdenken auf eine strukturierte Erfassung umzustellen.

Das geht bereits mit Open-Source-Ansätzen und einem Texteditor zur Erfassung der Informationen in XML (z.B. mit DITA), JSON oder Markup und reicht bis hin zu vollwertigen Component-Content-Management-Systemen, die das für dich im Hintergrund übernehmen. Welcher Weg für dich der richtige ist, hängt stark von deinen Anforderungen ab. Wir beleuchten das mit unseren Kunden in der Konzeptionsphase und finden gemeinsam den Weg zum „perfect-fit“. Egal welchen Weg du wählst, wichtig ist, dass du es tust und damit die Grundlage für moderne Softwaredokumentation schaffst. Denn m.E. geht moderne Softwaredokumentation, die die vollen Potentiale der Technik ausschöpfen, nicht mehr ohne. Du solltest allerdings vor einer zu vorschnellen Entscheidung zur „Systemlandschaft“ absehen. Der zunächst vermeintlich „kostengünstige“ Ansatz mit Open-Source-Tools und offenen Standards, kann sehr schnell zur Kostenfalle werden, wenn im Unternehmen keine Expertise für die ganze Informationsverarbeitungskette vorhanden ist.

Tipp 5: Achte auf die Texte innerhalb der GUI

Moderne Softwaredokumentation ist nicht mehr das eine PDF-Benutzungshandbuch, welches wir zum Produkt ausliefern. Moderne Softwaredokumentation ist verteilt in Informationshäppchen, die immer dort aufgerufen werden, wo sie den Anwendern am meisten dienen. Wenn der Platz es hergibt, daher genau dort, wo sich die Anwender ohnehin befinden – Auf der Softwareoberfläche. Versuche also (sprachlich, inhaltlich) den bestmöglichen Bezug von der Softwareanleitung zu den Oberflächentexten herzustellen. Im besten Fall hast du sogar die Möglichkeit, diese zu reviewen und Verbesserungsvorschläge an die Entwicklung zu geben. Fall dir das noch nicht bekannt ist: Texte auf der Softwareoberfläche nennen wir in Fachkreisen „Microcopy“ die Erstellung von diesen Texten gehört zum Fachbereich User-Experience und wird dort von UX-Writern (Rolle) erstellt. Technische Redakteure für Softwareprodukte eignen sich, wenn diese vorher geschult wurden, hervorragend für diese Rolle.

Tipp 6: Achte auf einen guten Review-Prozess

Lasse deine Informationsprodukte vor der Auslieferung stets überprüfen:

  • auf sprachliche Korrektheit von einem sprachlich versierten Reviewer
  • auf inhaltliche Korrektheit von einem Mitarbeiter mit Fachwissen
  • auf technische Korrektheit von einem Entwickler oder Tester

Wie das Softwareprodukt selbst, lassen sich auch deine Informationsprodukte „Testen“. Zum großen Teil sogar vollständig automatisiert. Hyperlinks und Verweise, Über- und Unterschriften, Umbrüche in PDF-Anleitungen etc. All das kannst du prüfen und so eine außerordentliche Qualität sicherstellen. Das schafft Vertrauen in deine Inhalte.

Tipp 7: Schaffe Ordnung in der Dateiablage

Stelle sicher, dass für dein gesamtes Team eine allgemein gültige Ablagestruktur gilt, diese befolgt wird und die Dateien zentral für alle Beteiligten zugänglich abgelegt werden. Arbeite NICHT mit lokalen oder per E-Mail verschickten Dateien. Lokale Kopien überholen sich ständig in deren Version und Aktualität. Du verlierst den Überblick über den letzten „Arbeitsstand“ deiner Informationen und kannst nur schwer nachvollziehen, wie sich deine Informationen im Verlauf der Zeit entwickelt haben. Dieses Chaos spiegelt sich in deinen Anleitungen. Inkonsistente, veraltetet oder schlichtweg falsche Informationen enttäuschen deine Nutzenden, was irgendwann zur Folge hat, dass diese deine Hilfe nicht mehr aufrufen und lieber direkt den Support kontaktieren. Das ist Verschwendung von Ressourcen (Zeit und Geld).

Tipp 8: Setze auf die Kraft eines Redaktionsleitfadens und konsistenter Terminologie

Gehe nicht davon aus, dass alle Teammitglieder das gleiche Verständnis für die Erstellung der nötigen Dokumentation haben, sondern halte alle wesentlichen Informationen und Abstimmungen zu Standardisierung, Struktur der Dokumente, Terminologie der Erfassungssprache, Schreibregeln für die Autoren usw. schriftlich und zentral für alle zugreifbar fest. Kommuniziere diese Regeln klar an alle Beteiligten.

Kurz: Sorge dafür, dass jede Person im Team gleich schreibt und so deine Informationsprodukte wirken, wie aus einem Guss.

Tipp 9: Schreibe Topic-orientiert

Topic = in sich geschlossene Informationseinheit, die genau eine Frage beantwortet und durch Verlinkungen und verwandte Themen die Relation zu anderen Topics sicherstellt. Topics sind Informationshäppchen, die genau ein Thema bearbeiten und dieses auch abschließen. Ein Topic hat zudem immer eine konkrete Aufgabe. Gängige Topic-Typen sind Task (Aufgabe), Concept (Beschreibung/Konzept), Reference (Referenz/Nachschlagewerk/Datenblatt).

Jeder Topic-Typ hat einen konsistenten Aufbau und ist dadurch direkt als eines dieser Topics identifizierbar. Schreibst du beispielsweise einen Task, also eine Handlungsanleitung, dann folgt diese einer klaren Struktur und ist direkt als solche für die Anwender erkennbar. Es ist direkt klar: Hier muss ich als lesende Person handeln. Zudem kannst du ein Topic allein anzeigen, mit Metadaten versehen und kontextsensitiv aufrufen. Isoliert und dort, wo die Information benötigt wird. Das ist ein Vorteil im Vergleich zu 700 Seiten PDF-Benutzerhandbuch, in dem sich die Zielgruppe diese Info erst über das Inhaltsverzeichnis suchen muss.

Tipp 10: Bilde dich stetig im Bereich Softwaredokumentation weiter

Schau dich um und halte deine Augen offen. Denn du selbst bist nicht nur erstellende Person von Informationsprodukten, sondern täglich auch nutzende Person eben solcher Systeme, die deinen Arbeitsalltag erleichtern. Öffne doch mal die Anleitungen zu den Produkten, die du nutzt und schaue dir an, was deine Branchenkollegen so tun.

Schaue dir gute Beispiele ab und übernimm diese in deine Anleitungen. Sei neugierig, mutig und bereit für Veränderung. Vergiss dabei nicht, deine Leitfäden aktuell zu halten. Das ist wichtig!

Abonniere Newsletter zu den neuesten Trends, besuche Messen und nimm an Weiterbildungsseminaren und Webinaren teil. So bleibst du in der schnelllebigen Welt der Softwareentwicklung auf dem neuesten Stand, nimmst Ideen mit und findest mögliche Lösungsansätze, um neue Herausforderungen anzugehen.

Auch wir bei STYRZ haben in unserem Weiterbildungsbereich einiges für dich zu bieten. Schau doch mal vorbei!