Software-Dokumentation: Agil zum Ziel
Wenn Technische Redakteure Software dokumentieren, arbeiten sie oft mit agil organisierten Entwicklungsteams zusammen. Im Vergleich zum Beispiel zum Maschinenbau ändert sich damit die Art und Weise, wie die Dokumentation entsteht: Sie wächst Schritt für Schritt mit dem Produkt. Wo liegen die Herausforderungen für Unternehmen, die dokumentationsintensive Software entwickeln? Und wie lassen sie sich im Redaktionsalltag lösen? Auf diese Fragen geben wir Antworten und zeigen im Use Case, wie die Technische Redaktion des Software-Herstellers Adcubum agil arbeitet.
Weshalb Software-Entwickler oft agil arbeiten
In der Software-Entwicklung zählt Geschwindigkeit, also, dass ein für den Kunden wertvolles Produkt möglichst schnell auf den Markt gelangt. Doch mit dieser Einführung ist die Arbeit noch nicht beendet. Das Produkt wächst kontinuierlich um neue Funktionen, Sicherheitsupdates sind nötig. Eine Software ist also meist nie fertiggestellt, im Gegensatz zu einer Maschine bei ihrer Auslieferung.
Die Anforderungen an eine Software und die digitale Welt entwickeln sich weiter und damit auch das digitale Produkt selbst. Mit agilen Methoden können Entwickler diesem Umstand gerecht werden. Sie sammeln neue Anforderungen, formulieren diese in sogenannte Stories um und priorisieren sie. Dann bauen sie in Sprints und im Team mit Testern und Agile Writern die beste Lösung für die jeweilige Anforderung.
Hoher Informationsbedarf bei Software-Anwendern
Insbesondere Experten-Software erzeugt einen enormen Informationsbedarf bei Anwendern, etwa IT-Administratoren oder Endnutzern. Manchmal müssen Anwender erst Konzepte und Verfahren erlernen, bevor sie sicher und effizient mit einer Software arbeiten können. So ist es kein Wunder, dass der Bedarf an guter Software-Dokumentation in Form von Handbüchern, Online-Hilfen, Tutorials, E-Learnings etc. ungebremst groß ist. Perspektivisch wird im Bereich Software mit der zunehmenden Digitalisierung der Arbeitswelt der Bedarf weiterhin steigen.
Unterschiedliche Zielgruppen in der Software-Dokumentation
Ein typisches Charakteristikum von Software-Dokumentation ist die Vielfältigkeit der Themen und Zielgruppen. Ein Beispiel: Ein IT-Unternehmen bietet eine Software zur Steuerung von Produktionsprozessen an. Wen muss die Dokumentation mit ihren Inhalten ansprechen?
Zum einen die Anwender der Software. Weil sie mit der Software aus unserem Beispiel aber nicht nur Prozesse steuern, sondern vor allem auch die Prozesslogik projektieren können, haben wir zwei unterschiedliche Anwendergruppen: Anlagenbediener und Projektierer.
Zum anderen sind es die Administratoren der Software. Und weil sich diese Software über eine API programmieren lässt, als vierte Zielgruppe Software-Entwickler. Diese beiden Zielgruppen benötigen neben der klassischen IT-Dokumentation für die Programmierung auch nachvollziehbar kommentierten Code, in dem sich wichtige Funktionen, Methoden und Parameter direkt im Quelltext erkennen lassen.
Jede dieser Zielgruppen löst unterschiedliche Aufgaben mithilfe der Software. Und so hat jede eigene Informationsbedarfe, die in der Technischen Dokumentation berücksichtigt werden müssen.
Video: UX Writing
Technische Redaktionen am Entwicklungsprozess zu beteiligen, ist nicht die einzige Möglichkeit: UX Writing ist die Disziplin, Software-Texte so zu gestalten, dass sie für User so verständlich wie nur möglich ist. Sie erfahren im Video zu UX Writing außerdem:
- Was UX Writing ist
- Was für gutes UX Writing spricht
- Welche Qualitäten gute UX Writer mitbringen
Typische Herausforderungen in der Software-Dokumentation
Zur Vielfalt unter den Zielgruppen kommen weitere Herausforderungen hinzu:
- Inhalte der Dokumentation: Es macht für die Dokumentation einen großen Unterschied, ob nur eine Version eines Software-Produkts oder mehrere Versionen parallel dokumentiert werden müssen. Ein zusätzlicher Komplexitätsgrad entsteht, wenn die Software kundenindividuell konfigurierbar ist, und die Redaktion beim Erstellen der Dokumentation nicht weiß, mit welchem Leistungspaket die Anwender konkret arbeiten. Und natürlich ist der Übersetzungsbedarf ein wichtiger Faktor.
- Redaktionsprozess: Software-Engineering bedeutet in vielen Unternehmen heute agile Methoden. Das ist für die Software-Entwicklung sicher eine gute Entscheidung, nur müssen in dem agilen Prozessdesign auch die Bedürfnisse der IT-Dokumentation systematisch berücksichtigt werden. Nur so ist sichergestellt, dass die Dokumentation einigermaßen zeitgleich mit der Software für den Kunden verfügbar ist.
- Veränderte Nutzererwartungen: Insbesondere für Software-Anwender im professionellen Umfeld ist die digitale Informationsbeschaffung heute Standard. Sie wollen Detailinformationen einfach, schnell und problembezogen finden. Rein dokumentbezogene Ansätze, die diese Details in mehrere Hundert Seiten langen PDF-Handbüchern „verstecken“, gehen an diesen Bedürfnissen vorbei. Der Bedarf nach konzentriertem und sofort verwertbarem Wissen spiegelt sich auch in der steigenden Relevanz von Instruktionsvideos wider. So ist es kein Wunder, dass die Technische Kommunikation reagiert und immer mehr Software-Anbieter Konzeptwissen oder einfache Abläufe als Bewegtbild aufbereiten.
Mit System zum Ziel: Software-Dokumentation geschickt optimieren
Wie gehen Software-Unternehmen am besten mit diesen Anforderungen an die Software-Dokumentation um? Wichtig ist, nicht einfach irgendwo anzusetzen, sondern die Weiterentwicklung der Dokumentation gezielt vom Istzustand aus zu steuern. Wenn Sie gerade vor dieser Herausforderung stehen, sollten Sie die folgenden drei Punkte in Ihrer Optimierungsstrategie berücksichtigen:
1. Zielgruppengerechtes Medienkonzept
Welche Informationsmedien und -kanäle will Ihre Technische Redaktion Ihren Kunden zur Verfügung stellen? Und welche Inhalte wollen oder müssen Sie dort kommunizieren? Wenn wir noch einmal zu unserem Beispiel zurückkehren, könnte das Medienkonzept für das Software-Unternehmen so aussehen:
Als PDF werden nur noch Inhalte ausgeliefert, die aus rechtlichen Gründen in gedruckter Form vorliegen müssen. Für die Zielgruppe Anlagenbediener und Software-Entwickler ist eine moderne, browserbasierte Hilfe im Format HTML5 die Hauptinformationsquelle. Einfache Abläufe werden darin als Schritt-für-Schritt-Anleitung erklärt. In der browserbasierten Hilfe können neben den klassischen Text- und Bildinhalten auch Videos angezeigt werden. Weil der Content modular aufgebaut und intelligent verschlagwortet ist, können Anwender gezielt auf spezielle Inhalte zugreifen.
Zusätzlich zur Hilfe gibt es eine webbasierte Knowledge-Base, auf die Anwender per Browser zugreifen können. Die Knowledge-Base ist auf Antworten zu Einzelfragen optimiert und setzt sich zum Teil aus den Hilfe-Inhalten, zum Teil aber auch aus Hilfsangeboten, die im Support entstehen, zusammen.
Mit Ausnahme der PDF-Dateien lassen sich alle Medien automatisch updaten. So ist gewährleistet, dass die Hauptinformationsquellen (in unserem Beispiel HTML5-Hilfe und Knowledge-Base) immer auf dem aktuellen Stand sind.
2. Passgenaue Prozesse für die agile Dokumentation
Wer im Unternehmen erstellt welche Informationen? Wie sind die Informatiker in der Entwicklung und die Technische Redaktion produktiv miteinander verzahnt? Welche Standards gelten für Text, Grafiken und Bewegtbild? Wie müssen Informationen verschlagwortet werden?
All das sind Fragen, die in den Bereich des Redaktionsprozesses fallen. Je mehr Kanäle Sie in Ihrem Medienkonzept definiert haben, desto wichtiger ist es, dass die Arbeitsprozesse reibungslos laufen.
3. Professionelle Tool-Umgebung für die Software-Dokumentation
Ein unentbehrlicher Helfer auf diesem Weg ist ein modernes Redaktionssystem. Mit einem Component Content Management System (CCMS) als Organisationszentrum können Sie zum einen flexibel die erforderlichen Kanäle aus einer Datenquelle bespielen (mehr zu Single Source of Publishing erfahren). Zum anderen lassen sich unterschiedliche Mitspieler in den Redaktionsprozess einbinden – von Redakteuren über Projektmanager, Fachexperten (z. B. Entwickler) bis hin zu Review-Verantwortlichen.
Video: Agile Software-Doku bei Adcubum
Im Zweifel fragt man am besten beim Profi nach und wer ist hier besser geeignet als ein Documentation Lead der Software-Spezialisten Adcubum? Sven Schmitt berichtet aus der Praxis, was es heißt, in einem agilen Umfeld Technische Doku zu schreiben.
Use Case: Agile Dokumentation in der Software-Entwicklung von Adcubum
Wie funktioniert es in der Praxis, wenn die Technische Redaktion gemeinsam mit dem Entwicklungsteam agil arbeitet? Einblicke teilt Sven Schmitt, Technischer Redakteur beim Quanos-Kunden Adcubum. Das Unternehmen ist die Nummer 1 in der Schweiz, wenn es um die Software-Herstellung für Kranken- und Unfallversicherungen geht. 1997 von fünf Studenten der Universität St. Gallen gegründet, hat sich das Unternehmen mit acht Standorten und über 400 Mitarbeitern zu einer festen Größe entwickelt. Adcubum ist Gewinner des europäischen Xcelent-Awards für Kundenzufriedenheit. Agile Entwicklungsprozesse, mit denen sich Kundenbedürfnisse schnell und präzise umsetzen lassen, sind ein wesentlicher Grundpfeiler für diesen Erfolg.
Technischer Redakteur in Entwicklungsteam eingebettet
Aus der Sicht von Sven Schmitt ist die enge Einbettung in die Entwicklungsprozesse und damit in das Entwicklungsteam entscheidend. Technische Redakteure nehmen in einem agilen Team eine eigene Rolle ein und verantworten die Dokumentation des Entwicklungsfortschritts und die Einhaltung der Terminologie. Dies grenzt Technische Redakteure deutlich von den Entwicklern, dem Scrum Master als Moderator und Unterstützer des Teams sowie von der Qualitätssicherung ab.
Der Product Owner steht zwar außerhalb des Entwicklungsteams, spielt aber eine wichtige Rolle, weil er Anforderungen definiert und priorisiert. Dies gilt auch für die Qualität der Dokumentation, sodass der Product Owner immer auch die Technische Redaktion im Blick haben muss.
Teamübergreifende Standards für Technische Redakteure
Ebenfalls außerhalb des Entwicklungsteams organisieren sich die Querschnittsaufgaben der Technischen Redaktion. Neben den konkreten Projektaufgaben müssen sich Technische Redakteure und Redakteurinnen auch auf teamübergreifende Standards verständigen. Dazu treffen sie sich in sogenannten Gilden, denen ein Documentation Lead vorsteht. In den zweiwöchentlichen Gilden-Veranstaltungen besprechen sie übergreifende Dokumentationsthemen, die für alle Technischen Redakteure wichtig sind – unabhängig von ihrer fachlichen Zugehörigkeit zu einem Team.
Arbeiten in Sprints – auch für den Redakteur
Die Arbeit des Entwicklungsteams organisiert sich in Sprints, kurzen Arbeitseinheiten von ein bis vier Wochen. In diesen Sprints werden Anforderungen erfasst, bewertet, umgesetzt und dann ein Kundenfeedback eingeholt. Diese Rückmeldung und die Erfahrungen aus dem Sprint fließen in den nächsten Sprint ein. Sprints decken nur Teile des Entwicklungsprozesses ab. Sie folgen so lange aufeinander, bis das Produkt übergabereif ist.
In jeder Phase der Sprints muss ein Technischer Redakteur dokumentationsrelevante Aufgaben erkennen, bearbeiten und prüfen. Mit seinem Wissen zu Terminologie und zur Vermittlung von Inhalten übernimmt er eine wichtige Beratungsfunktion im Entwicklungsteam. Da die Dokumentation Bestandteil des Produkts ist, stehen seine Arbeitsergebnisse ebenso im Kundenreview wie die programmierten Bestandteile der Software.
Video: Agile Software-Doku mit SCHEMA ST4
In diesem Video erfahren Sie, wie die Software-Dokumentation bei Adcubum mit einem Redaktionssystem verläuft, welche Anforderungen der Software-Hersteller dabei konkret hatte und wie diese vom gefundenen CCMS erfüllt wurden.
Agile Redaktion: viele Vorteile, einige wenige Herausforderungen
Wie sieht die Bilanz für die Technische Redaktion in einem solchen Umfeld aus? Als positiv betrachtet Sven Schmitt die enge Anbindung an den Entwicklungsprozess. Dadurch fließen Informationen leichter und Feedback aus Entwicklung und vom Kunden kommt schneller beim Technischen Redakteur an. Er kann leichter Einfluss auf den Entwicklungsprozess nehmen, wodurch sich Fehlentwicklungen leichter vermeiden lassen. Extrem hilfreich ist seiner Meinung nach auch die Arbeitsweise in einem Scrum-Prozess: Dokumentation kann auf diese Weise nach und nach fertiggestellt werden, statt als ein großes Ganzes zum Ende des Entwicklungsprozesses. Die Bedürfnisse der Dokumentation werden immer gesehen, da sie ein integraler Bestandteil (und damit eine integrale Anforderung) im Entwicklungsprozess sind.
Doch die enge Einbindung ins Entwicklungsteam hat auch ihre Nachteile. Die Einhaltung von Text- und Terminologiestandards über die verschiedenen Teams hinweg erschwert sich. Nicht immer lässt sich die Dokumentation parallel zur Entwicklung vollziehen oder es kommt zu unnötigen nachträglichen Textanpassungen. Die Beschleunigung der Releases und die Vervielfachung der Softwareversionen machen die Arbeit des Technischen Redakteurs ebenfalls schwerer.
Aber alles in allem lässt sich festhalten: Technische Redakteure können in agilen Prozessen gut arbeiten, wenn sie eine feste Rolle im Entwicklungsteam haben und ihre Bedürfnisse in den Sprints Gehör finden.
