© Wuttichai Kaewklang / 123RF.com

Worauf sollte man beim Dokumentieren besonders achten? Wie integriert man Dokumentation am besten in seine Prozesse? Welche Tools bieten sich an? Wie sehr sollte man ins Detail gehen? Das geben Doku-Experten von Suse und Owncloud hier zum Besten.

Die Autoren von Softwaredokumentation sehen sich oft mit gravierenden Vorurteilen konfrontiert. Doku, das sei ja quasi keine technische Arbeit, kein IT-Job, hört man immer noch häufig. Manche IT-Graubärte erklären Doku gar zur reinen Frauenarbeit. Nicht immer erfahren die Verfasser und Verfasserinnen technischer Dokumentation die Wertschätzung, die ihr Job eigentlich verdient. Doch das Profil des Technischen Redakteurs – ein eigenes Studienfach an zahlreichen Universitäten – sieht viele Begabungen als erforderlich an.

Darunter finden sich einige, die auch für einen Job im Management nicht von Nachteil wären, wie vernetztes Denken oder die Fähigkeit, komplizierte Sachverhalte in einfache Sätze zu verpacken. Technische Redakteure sollten zwischen zwei grundverschiedenen Sachgebieten eine Brücke schlagen können und Einfühlungsvermögen sowie Sprachgefühl mitbringen. Sie müssen ein Gefühl für das Gestalten und Strukturieren von Texten haben, aber auch in der Lage sein, selbst dem schweigsamsten Kernel-Nerd die wichtigen Informationen aus der Nase zu ziehen. Rund 80 Prozent des Studiums widmen sich dabei dem redaktionell-sprachlichem Handwerk, nicht der Technik.

Beruf mit Zukunft

Jeder, der schon einmal “in der Doku” gearbeitet hat, kennt die ungläubigen Gesichter der Techniker oder Manager, wenn diese zum ersten Mal hören, es gäbe Regeln für diesen oder jenen Satzbau oder für diese spezielle Textsorte. Oft ist auch schwer zu vermitteln, dass es einen Unterschied macht, ob man einen Text fürs Internet, Print, die Online-Hilfe oder für das PDF der High-Value-Kunden schreibt.

Das Portal studieren.de [1] sieht – ChatGPT zum Trotz – für Dokumentationsexperten eine glorreiche Zukunft: “Technischen Redakteur*innen werden gute Zukunftsaussichten vorausgesagt: Zum einen liegt das daran, dass sie vielfältig einsetzbar sind, zum anderen, dass immer mehr Produkte auf den Markt geworfen werden, die einer Erklärung bedürfen. Einsatzmöglichkeiten finden sie bei fast allen Industrieunternehmen – vom Konsumgüterbereich bis hin zum Maschinen- oder Fahrzeugbau, in der Telekommunikation, der Computerbranche und im Bereich der Optik.”

“Kommunikation ist das A und O. Auch auf und zusammen mit den höchsten Managementebenen muss der Dokumentationsexperte in der Lage sein, Bewusstsein (Awareness) für die Wichtigkeit des Themas zu schaffen. Gerade die Chefetagen müssen verstehen, dass Dokumentation ein wesentlicher Bestandteil der Softwareprodukte und -lösungen ist, ohne den der Anwender kaum Erfolg haben wird.”

Das sei allerdings immer noch nicht überall angekommen, erklärt Meike Chabowski, Dokumentationsstrategin (Documentation Strategist) beim Linux-Vendor Suse (Abbildung 1). “Wer Dokumentation nur als Cost Center sieht, hat ein Problem. Dokumentation ist ein grundlegender Service, den der Kunde mit dem Produkt mitbezahlt”, stellt sie klar. Ohne Zusammenarbeit mit anderen Teams geht da gar nichts, das Ergebnis kann dann nicht gut werden. Experten aus allen beteiligten Teams müssen zusammenarbeiten, auch das Feedback von externen Fachleuten ist wichtig. Dazu meint Chabowski: “Nicht jeder kann schreiben, aber jeder kann zur Dokumentation beitragen – sei es durch Feedback, Anregungen, Fehler finden, Text korrigieren und vieles andere mehr.”

Abbildung 1: Meike Chabowski ist Documentation Strategist bei Suse.

Was dokumentieren?

Gute Dokumentation wird immer wichtiger: Auch in Unternehmen und gerade im Kontakt mit Endgeräten nehmen viele Menschen Geräte und Software als immer komplizierter wahr, allen Fortschritten in Sachen UX/UI-Design zum Trotz. Firmen erkennen den Wert guter Dokumentation, sowohl für die Produkte als auch für die Prozesse innerhalb der Firma – Stichwort: Knowledge Management. Gerade bei Letzterem gewinnt das Thema Nachhaltigkeit mehr und mehr an Bedeutung.

Eine zweite Jugend erfuhr das Wissens- und Know-how-Management in Unternehmen spätestens 2021, als Marktführer Atlassian, Hersteller der in den meisten IT-Firmen eingesetzten Systeme Confluence, Jira und Trello, seine Preise massiv erhöhte und begann, Kunden in die Cloud zu zwingen. Da zeigte sich, wie teuer es werden kann, sich nur auf einen Monopolisten zu verlassen. Hersteller von Open-Source-Alternativen zu Atlassian-Produkten haben derzeit Konjunktur. Auch das Linux-Magazin zeigte [2], wie man es schafft, trotz des Trubels im Alltagsbetrieb eben jenen Alltag zu dokumentieren und die Prozesse und Informationen aufzuzeichnen, die die Mitarbeiter häufig brauchen. Dieselben Methoden greifen auch bei der Produktdokumentation.

Auch die vielen Anleitungen im Internet [3] sind sich einig: Gute Dokumentation fängt mit einem sauberen Prozess an, hört dort aber noch lange nicht auf. Meist braucht es drei bis fünf verschiedene Gattungen, die von Quickstart-Guides (“Getting Started”) über Installations-, Admin-, User und Referenzdokumentation (mit zum Beispiel allen API-Befehlen) bis hin zu monothematischen How-tos oder Best Practices reichen. Meist gibt es spezielle Tools für jede Gattung. Das Swagger-Toolset [4] beispielsweise hilft bei den einzigen Handbüchern, die sich halbwegs automatisiert schreiben lassen: API- und Referenz-Dokumentationen.

Klare Prioritäten

Die Prioritäten, was zu dokumentieren ist, sollte stets das Produktmanagement vergeben: Dort laufen die Fäden zusammen, was den Bedarf der Kunden und die heißesten neuen Features angeht. Auf keinen Fall sollten Developer dokumentieren oder die Scrum Master entscheiden, was dokumentiert werden sollte. Sie haben fast immer nur die Innenansicht, nicht den Überblick. Das Was ist ohnehin meist ein Kompromiss aus verschiedensten Fragen: Was ist neu? Was muss man erklären? Was brauchen die Kunden (dem Vertrieb, den Kundenberatern und Consultants zufolge)? Wofür stehen Ressourcen bereit, was hat Priorität?

Dass dabei zahlreiche Kollegen und Manager ein Wörtchen mitreden wollen und dürfen, macht die Sache nicht einfacher. Ein Dokumentationsexperte muss heute zwingend auch Fähigkeiten des Projekt- und Zeitmanagements, agiler Methoden und Verständnis für Unternehmensprozesse und -ressourcen mitbringen – und eine saubere Triage beherrschen. Die schönste Doku hilft niemandem, wenn sie nicht gelesen oder nicht benötigt wird. Sie wirft auch keinen messbaren ROI (Return on Investment) ab und kostet nur Geld – so ein oft gehörter Vorwurf.

Aber ein guter Dokumentationsprozess steht im engen Austausch mit der Qualitätssicherung. Weil die Dokumentation eines neuen Produkts ja mit dem Produkt fertig sein muss, aber meist länger dauert, testen die Doku-Schreiber meist lange, bevor die QA-Kollegen anfangen. Auch gemeinsame Sprints sind denkbar – und manchmal dringendst nötig –, bei denen Development, QA und Doku sich zum Erstellen eines Handbuchs zwei Wochen in Klausur begeben.

Das sieht auch Martin Mattel (Abbildung 2) so: “Dokumentation ist nicht das Schreiben von ein paar Sätzen, sondern das Ergebnis einer intensiven, kollaborativen Arbeit über mehrere Abteilungen.” Der Wiener zeichnet verantwortlich für weite Teile der Dokumentation des Nürnberger Unternehmens Owncloud [5]. “Dokumentation kann man als einen Aspekt von QA sehen. Man braucht Manpower und einen Know-how-Stack, dann muss man sich noch in die Schuhe von anderen Menschen hineinversetzen können.” Es mache zwar einen großen Unterschied, ob man für Developer, User, Admins oder Manager schreibt. Am tiefen Verständnis der Sprache und etwas Talent für die richtige Formulierung komme man aber nicht vorbei, betont Mattel.

Abbildung 2: Martin Mattel ist Unternehmensberater aus Wien und schreibt seit vielen Jahren an der Dokumentation für Owncloud.

Qualifikationen

Ein guter Tech Writer zeichne sich aber auch durch proaktives Handeln, Interesse an der Sache (gerade auch in technischer Tiefe) und dem Spaß am Netzwerken mit anderen Abteilungen aus. Insel- und Silo-Denken müsse er oder sie aktiv vermeiden. Hartnäckigkeit, Lust an der “Forschungsarbeit” und Spaß an der Fehlersuche seien ebenfalls zwingend notwendige Charaktereigenschaften, so Mattel. “Doku ist Forschungsarbeit, beschreiben, interne und externe Zusammenhänge erkennen, einbauen, abgrenzen und wieder referenzieren, wo nötig. Das wird aber ganz anders wahrgenommen: Fürs Management sind das lästige Kosten, morgen soll das eh ChatGPT machen. Für die Entwickler ist Dokumentation oft nur ein lästiger Zeitdieb. Aber für den Anwender ist die Dokumentation oft der einzige Zugang zu den gesuchten Infos.”

Für Sales und Vertrieb ist gute Doku ein starkes Argument, warum der Kunde das eigene wohldokumentierte Produkt kaufen sollte und nicht das schlecht(er) dokumentierte der Konkurrenz oder das undokumentierte FOSS-Paket. Gerade bei Open-Source-Produkten wird Dokumentation immer wichtiger, weil hier potenzielle Kunden vielleicht schon wieder abspringen, wenn sie beim ersten Problem mit dem OSS-Projekt keine hilfreiche Beschreibung finden. Lange vor dem Erstkontakt mit der Herstellerfirma verliert diese so unter Umständen bereits Kunden. Ja, Dokumentation gehört auch zu den Services, mit denen OSS-Unternehmen wie Suse Mehrwert beweisen können (Abbildung 3).

Abbildung 3: Die Suse-Dokumentation ist in mehrere nach Zielgruppen gegliederte Sparten aufgeteilt.

Doku als Visitenkarte

Dazu meint Martin Mattel: “Dokumentation ist eine Visitenkarte. Mehr noch als die Webseite spiegelt sie die Professionalität eines Unternehmens wider. Sie schafft Vertrauen und Zuversicht und ist die Basis für konkrete Fragen. Aber sie ist auch Teil des Brandings für das Unternehmen, weil sie ja direkt auf die Anwender, die Kunden hin ausgerichtet ist.”

Auf der anderen Seite habe sie auch einen großen Einfluss auf die Entwicklung, so Mattel: “Im Idealfall wird der Code und das Resultat von Anfang an aus einem anderen Blickwinkel gesehen, weil die Dokumentation das beschreibt, was ist und funktioniert und nicht, was man gern hätte. Auch hier findet der hilfreiche Perspektivenwechsel statt – und da müssen die Dokumentationsmitarbeiter viel mit dem Support und der Service-Abteilung reden, damit der Fokus auf die wirklich hilfreichen, manchmal auch herausfordernden Klarstellungen gelegt werden kann. Dann kann die Dokumentation auch die Basis für weiterführende Dienstleistungen werden.”

An dieser Stelle kommt dann auch der eigentliche Wert der Dokumentation zutage, meint Mattel. Der werde von Marketing, Entwicklung, Kunden und Support sehr wohl gesehen, auch hinsichtlich eines ROI.

Klar definiertes Szenario

Der Teamleader Dokumentation bei Suse, Frank Sundermeyer (Abbildung 4), ist bei der weltgrößten eigenständigen Linux-Firma seit bald zwei Jahrzehnten in der Dokumentation [6] tätig. Er hat eine klare Vorstellung, worauf es bei professioneller Dokumentation zu achten gilt: “Es braucht ein klar umrissenes und definiertes Szenario, eine klare Struktur mit Zielen, Voraussetzungen und Umsetzung. Das meine ich nicht nur theoretisch – das Dokumentierte als Schreiber auch in der Praxis nachvollzogen und verstanden zu haben, hilft ungemein, die Qualität der Dokumentation zu steigern.” Gefragt, was denn die wichtigste Erfahrung sei, die das Suse-Dokumentationsteam in drei Jahrzehnten gemacht hat, erklärt Sundermayer: “‘Hands-on’-Experience ist durch nichts zu ersetzen, und Technical Writing ist interdisziplinäre Teamarbeit”.

Abbildung 4: Frank Sundermeyer ist Teamleiter im Dokumentationsteam bei Suse.

Dokumentation solle nach Möglichkeit stets parallel zum Schreiben in der Praxis getestet werden, betont Sundermeyer, weil sich so auch Fallstricke und Irrwege dokumentieren lassen, die ansonsten eventuell in Vergessenheit geraten. Auch die Entwicklung profitiert von dieser Vorgehensweise, da Technical Writer so nicht selten Fehler finden und rückmelden. Hier kommt ebenfalls potenzieller ROI ins Spiel: “Wir machen zum Beispiel die Suse Best Practices teilweise auch in Zusammenarbeit mit unseren Consultants und beschreiben darin besondere und verbreitete Kundenszenarien. Bei der Umsetzung beim Kunden muss das ja entsprechend dokumentiert sein, sodass die Doku aus der Alltagsarbeit schon fast von selbst herausfällt. Das Ganze kann dann anschließend ein Technical Writer bearbeiten und publikationsfähig machen.”

Das sagt auch Martin Mattel: “Dokumentation sollte immer eingebunden werden, ganz am Anfang und ohne Einschränkungen.” Und Meike Chabowski bestärkt, dass es immer darum gehe, Bewusstsein zu schaffen bei allen Verantwortlichen, Entwicklern, Entwicklungsteams und Managern: “Wir dokumentieren nicht für euch oder uns, sondern für unsere Anwender. Ohne Dokumentation können die meisten Produkte nicht genutzt werden. Dokumentation ist ein grundlegender Service für den Kunden.”

Wie viel Details?

Auch der Tiefgang spielt eine wichtige Rolle. Frank Sundermeyer definiert Dokumentationen normalerweise als “Schritt-für-Schritt-Anleitungen, die für eine spezielle Zielgruppe geschrieben werden”. Alle erforderlichen Grundkenntnisse müssen vorab in einem Bereich “Voraussetzungen” abgeklärt sein. “Damit ergibt sich die Flughöhe eigentlich automatisch.”

Eine vorherige Analyse der Zielgruppe und der Leserschaft hält als Technical Writer auch seine Kollegin Julia Faltenbacher für enorm wichtig: “Vor dem Schreiben muss eine Zielgruppenanalyse durchgeführt werden, die die Vorkenntnisse und Bedürfnisse der Leser festhält, damit diese stets auch beim Schreiben beachtet werden können. Erst daraus ergibt sich dann zum Beispiel auch das Ausgabeformat.” Ein Techniker, der in der Werkstatt vor einer Maschine steht, benötigt ein anderes Format als der, der vor dem Büro-PC sitzt. Im Internet gelten dann noch einmal andere Regeln: Viele Teams behandeln für Suchmaschinen optimierte Texte (SEO) als eigene Ausgabekategorie.

Ohne Doku kein Produkt

Meike Chabowski mahnt: “Dokumentieren ist nicht nur ‘einfach was schreiben’. Softwaredokumentation besteht zunächst überwiegend aus Recherche und Planung. Das Schreiben an sich ist der vom Aufwand her geringste Teil.” Zwei Wochen Recherche, Testen und Kommunizieren für einen hilfreichen Absatz, der ein großes Problem vieler Kunden löst, kann da schon einmal vorkommen.

Ideal ist es, wenn schon die Entwickler eine eigene, interne Vorabdoku erstellen, auf der man aufbauen kann. Das muss aber schon in der Aufwandsplanung eingepreist werden. Eine Checkliste, auf der “Dokumentieren und Kooperation mit dem Doku-Team” als verpflichtende Aufgabe (Mandatory Task) eingestuft ist, hilft da sehr. Ein Produkt ist erst fertig, wenn es Dokumentation gibt.

Zusammen mit den Entwicklern nehmen moderne Dokumentationsteams Teil am agilen Prozess der Softwareentwicklung, machen Milestones mit und nehmen an Sprints teil. Separate Doc Sprints oder Doc Days – Tage, an denen nur an der Dokumentation gearbeitet wird – helfen sehr, auch beim Erzeugen der Awareness. Kein Wunder, dass es ein gutes Zeichen für ein funktionierendes Dokumentationsteam ist, wenn es sich nahtlos in die Tools und Sprachen integrieren kann, die die Entwickler nutzen. Derlei Kenntnisse beschleunigen den Dokumentationsprozess enorm und reduzieren den Overhead in anderen Teams.

Aber auch die Techniker mit Anwenderkontakt müssen Zeit einplanen – und das ist oft teuer. Wenn Consultants, Sales Engineers, Support und Presales Feedback geben sollen, müssen sie Stunden dafür reservieren – Stunden, in denen sie erst einmal keinen Umsatz für die Firma machen. Aber genau diese wertvolle Zeit, in der das Feedback aus der Zusammenarbeit vor Ort mit dem Kunden und bei der Implementierung von Lösungen in die Doku fließt, ist bares Gold wert. Derlei können kein Softwareentwickler und kein Technischer Redakteur liefern, weil ihnen die Real-Life-Erfahrung mit den Produkten und Lösungen fehlt.

Gute Doc-Teams machen es den Zulieferern so einfach wie möglich – egal, ob diese in Sales oder Development arbeiten, egal, welche Expertise in Sachen Dokumentation vorliegt. Ein gutes Dokumentationsteam sollte nach außen werkzeug- und formatagnostisch sein. Jeder Input ist willkommen, egal in welcher Datei.

Tools, Tools Tools!

Thomas Schraitle, ebenfalls seit vielen Jahren im Dokumentationsteam von Suse tätig, legt den Fokus noch mehr auf die technischen Aspekte: Ihm sind Konsistenz, Zielgruppenbezug und eine stimmige, gute Struktur wichtig, in einem ansprechenden, benutzerfreundlichem Layout. “All diese Faktoren bestimmen, wie deine Dokumentation wahrgenommen wird.” Bei der Integration in die Prozesse helfen Style Guides, Definitionen, Vorlagen und Templates, aber auch klare Prozessdefinitionen und Softwarearchitekturen wie Continuous Integration.

Dazu sagt Schraitle: “Alle erwarten aktuelle Dokumentation, jeder sollte zur Doku beitragen und jeder kann helfen. Aber man muss sich informieren und sich mit dem Projekt absprechen.” Es hilft ungemein, einen guten Korrektor zu haben, der die Beiträge redigiert, auch weil das Dokumentieren am Ende eben doch nicht so einfach ist, wie es sich viele vorstellen. Auch Schraitle ist sich sicher: “Der Satz ‘Aber schreiben kann doch jeder’ stimmt halt so nicht. Trotzdem kann jeder zur Doku beitragen.”

Um das sicherzustellen, sollte sich ein Dokumentationsteam in einer größeren Firma offen aufstellen. Ohne Versionskontrollsystem wie Github geht da schon mal gar nichts mehr, meint Schraitle: “Welches System man wählt, ist weniger wichtig. Wichtig ist, dass es gemacht wird! Ohne das würde ich heute kein Projekt starten, egal ob Dokumentation oder etwas anderes. Git/Github bietet sich an, da es weit verbreitet ist und die Option offenlässt öffentlich oder im Privaten zu arbeiten. Wenn sich ein größeres Team mit Dokumentation beschäftigt, muss unbedingt ein CI-System wie Jenkins aufgesetzt werden. Das regelmäßige Bauen der Dokumentation sorgt auch dafür, dass Mitarbeiter mehr auf Qualität achten und Fehler frühzeitig entdeckt werden. Jenkins spuckt dann im Idealfall regelmäßig alle benötigten Output-Formate aus, vom PDF zu EPUB, HTML (Single File oder für viele kleine Seiten) und alle anderen Formate.”

Beim Thema Dokumentationsformat gibt es mancherorts regelrechte Flamewars zwischen den Fans der einen oder anderen Lösung. Doch Schraitle weiß: “Ob du in Markdown, ReST, Asciidoc, Docbook oder etwas anderem schreibst, ist weniger wichtig. Nutze das Format, das für dein Projekt am besten passt. Das Format legt auch die Tools fest und nicht umgekehrt. Kenne die Vor- und Nachteile jedes Formats, informiere dich vorher und sieh dir an, was deine Kollegen in der Entwicklung verwenden.”

Wenn all das geklärt ist, müssen die Verantwortlichkeiten entschieden werden: “Wer betreut ein Kapitel? Wer darf Änderungen einpflegen? Wer überprüft den Stil, Rechtschreibung und die technische Richtigkeit? Wer darf das Endprodukt veröffentlichen? Je größer das Team wird, desto mehr muss man sich diesen Fragen stellen.” Da kommen dann auch Übersetzungen ins Spiel: Gibt es nur eine Sprache? Oder soll das Dokument in diverse andere Sprachen übersetzt werden? Ist Letzteres der Fall, benötigt man weitere Tools, die Übersetzungen ermöglichen (Abbildung 5). OpenSuse verwendet dafür beispielsweise Weblate [7]. Dem stimmt auch seine Kollegin Julia Faltenbacher zu: “Wer bei der Lokalisierung ein paar Grundregeln beachtet, bekommt auch bessere Qualität in der Originalsprache. Wir haben dazu einige Abschnitte in unserem Styleguide.” [8] Best Practices für Owncloud finden sich auf der Github-Seite des Projekts [9].

Abbildung 5: OpenSuse nutzt das Übersetzungsmanagementwerkzeug Weblate, um die Übersetzungen und Lokalisierungen zu koordinieren.

Viele Dokumentationsexperten betonen, dass die Werkzeuge und Toolchains immer nur Mittel zum Zweck sein sollten und nicht im Vordergrund stehen sollten. Suse nutzt DAPS [9], die Docbook Authoring and Publishing Suite (Abbildung 6). Oft kommt Asciidoc zum Einsatz, weil das Markdown-Format niedrige Einstiegshürden stellt, oder DocbookXML, weil XML vielseitiger beim automatischen maschinellen Verarbeiten ist. Das wird umso wichtiger, je mehr automatisierte QA und Tests man einbindet: Styleguide, Rechtschreibung, Corporate Identity, sogar Anbindung an den Open-Build-Service wären da denkbar. Auch das Suse Documentation Team muss da immer wieder nachforschen und verschiedene Frameworks vergleichen [11].

Abbildung 6: Bei Suse kommt die Docbook Authoring and Publishing Suite DAPS zum Einsatz.

“Man kann durchaus im Kleinen anfangen, mit einem Etherpad oder anderen kollaborativen Tools.” sagt Schraitle. Vor wenigen Jahren beschäftigte sich auch im Linux-Magazin ein Artikel mit Tools für kollaborative Dokumentations-Workflows [12]. “Wie man dann die vielen Bausteine zusammenbaut, hängt von vielen Faktoren ab, nicht zuletzt vom Know-how, Budget und davon, was die Kollegen in der Entwicklung schon verwenden.” Hauptsache, bestätigt auch Martin Mattel, ist doch, dass das Tool geeignet ist: “Das Framework, um die Doku zu schreiben, muss in der Lage sein, die Anforderungen zu bedienen, aber auch der Weiterentwicklung der Dokumentation standhalten können. Es muss auch zukünftigen Anforderungen gewachsen sein, Darstellungen wie Tabellen oder Referenzierungen müssen einfach umsetzbar sein. Hier auf quick & dirty zu setzen, rächt sich und kostet beim Aufräumen viel Zeit und Geld.”

Von ChatGPT in der Dokumentation ist er nicht überzeugt: Die Kosteneinsparung sei zu gering, auch weil die KI-Tools viel Recherche im Nachgang erforderten. Viel wichtiger ist da, sagt auch Frank Sundermeyer, dass die gewählten Tools miteinander kooperieren können. “Am Ende sollte man immer Werkzeuge und Formate wählen, die mit beispielsweise Git zusammenarbeiten, wenn alle Entwickler auf Github arbeiten.”

Der Umstieg von SVN auf Git vor bald zehn Jahren hat beispielsweise bei Suse zu einem fast exponentiellen Anstieg von konstruktiven Rückmeldungen und Beiträgen aus der Entwicklung geführt. Deutlich mehr Entwickler nutzten ohnehin Git. Eine wichtige Einstiegshürde war damit beseitigt, und das Backlog wuchs. Mit der Wahl eines Versionskontrollsystems wie Git geht allerdings eine weitere Entscheidung zwingend einher: Binäre Formate wie die gängiger Office-Suiten scheiden definitiv aus.

Verständliche Sprache

Und nach all der Planung, Kommunikation und Bewusstseinserweiterung gibt es dann ja noch die sprachliche Ebene, die sich als nicht minder komplex erweist. Gute Texte zu schreiben, ist eine Wissenschaft für sich. Chabowski rät, den Fokus auf die Verständlichkeit zu legen. “Ein Tech Writer schreibt keine Prosa, sondern eine Anleitung. Einfache Sprache, kurze Sätze, Wiederholungen von (Fach-)Begriffen, keine Ausschmückungen oder Füllwörter – das macht den Unterschied. Dokumentation muss nicht spannend oder abwechslungsreich sein, sondern auch bei komplexeren Themen nachvollziehbar und verständlich.” Hier helfen Spell- und Stylechecker, Checklisten und automatische QA, die das Einhalten von Regeln erzwingen.

“Unter Dokumentation erwarten Anwender heute aber auch viel mehr als nur geschriebene Texte. Ob die nächsten Generationen noch Dokus lesen, ist durchaus nicht ausgemacht”, ist sich Chabowski sicher. Kurze Videos mit Schritt-für-Schritt vorexerzierten How-to-Anleitungen, Podcasts, Grafiken – all das muss in die Dokumentation mit eingebaut werden, um den Konsum für die unterschiedlichsten Nutzergruppen zu ermöglichen. “Dafür braucht es wieder Planung, Zeit, entsprechende Werkzeuge und Experten. Dokumentationsfachleute dürfen Youtube, Tiktok und Instagram nicht unterschätzen”, mahnt Chabowski. Dokumentationsteams müssen hier eng mit dem Marketing zusammenarbeiten.

Aber auch die klassische Online-Hilfe ist eine notwendige Art der Dokumentation – eingebunden in die Software, ein Paradebeispiel für das, was auf Dokumentationsteams zukommt. Anwender erwarten keine dicken Bücher, Manuals oder Guides mehr, so wie das Suse-Handbuch, das die Firma in den 1990ern groß gemacht hatte. Die Experten sind sich einig: Lösungs- und Themen-basierter Dokumentation gehört die Zukunft; agil erstellt und für fast beliebige Ausgabeformate strukturiert.

“Der Anwender will sich nicht durch ein Buch durcharbeiten, sondern sucht gezielt nach Informationen, die ihm dabei helfen, ein ganz bestimmtes Problem in den Griff zu bekommen oder eine bestimmte Softwareumgebung aufzubauen”, erklärt Chabowski. Das gelinge nur mit modularen Ansätzen in der Dokumentation: “Wer kann, sollte von vorneherein mit Bausteinen arbeiten. Softwaredokumentation wiederholt sich oft, viele Schritte, Prozeduren, Abläufe, die dort beschrieben sind, kann man wiederverwenden. Dafür ist ein Dokumentenmanagement-Tool hilfreich.” Welches, das muss jedes Unternehmen selbst entscheiden, abhängig von der bereits verwendeten Toolchain.

Abbildung 7: Egal ob mit DocbookXML, Asciidoc oder Markdown: Viel wichtiger als die Tools ist das Ergebnis. Es muss klar, verständlich und ansprechend ausfallen. Die Owncloud-Dokumentation setzt dafür auf Antora und Asciidoctor.

Regeln und Best Practice

Bei den Interviews mit den Experten bemerkt man zwei Dinge: Erstens steht bei der Dokumentation nicht die Sprache oder die Grammatik im Vordergrund. Als wichtigste Komponenten für den Erfolg nennen sie Strukturen, Kommunikation und individuelle Fähigkeiten der Dokumentationsfachleute. Die Profis beschäftigt nicht die Frage, ob und wann man einen Fachbegriff übersetzt [13]. Für sie spielen weder die im Deutschen und Englischen sehr unterschiedlichen Regelungen für Koppelungen eine Rolle noch die Ratschläge für die Maximallänge eines verständlichen Satzes. Vieles davon betrachten die Doku-Fachleute eher als Mythen, die Dritte über professionelle Dokumentationsteams im Kopf haben [14].

Moderne Dokumentationsteams – vor allem im Open-Source-Bereich – sind also keineswegs nur detailverliebte Sprachfanatiker. Sie arbeiten genauso agil wie die Entwickler, mit denen sie kooperieren. Hier kommt ein weiterer Punkt ins Spiel: Gute Dokumentationsteams nutzen agile Tools und Methoden und können sich mit (fast) jedem Entwicklungsmodell von Waterfall bis Scrum koordinieren. Welche Tools genau zum Einsatz kommen – ob Framework, Sprache, Format, Versionskontrolle oder gar Editor – ist immer die letzte Frage, abhängig von den Umgebungsvariablen im Workflow der Entwickler und der Kunden. Wer seinen Workflow im Griff hat, der kann Input in jeder Form und in jedem Format annehmen – so wie DAPS bei Suse. (jcb)