Seite 3: Tipps, Tricks und Tools

Inhaltsverzeichnis

iX: Abseits von KI: Welche Best Practices und bewährten Techniken könnt ihr unseren Leserinnen und Lesern an die Hand geben, um den Dokumentationsprozess zu vereinfachen?

Charlotte: Dokumentation sollte meiner Meinung nach genauso zur Entwicklung gehören wie das Programmieren und Testen und nicht erst am Ende eines riesigen Projektes passieren. Heutzutage arbeiten die meisten Teams agil und schreiben den Code in kleinen Inkrementen – wieso nicht auch die Dokumentation? In meiner Firma haben wir uns zum Beispiel darauf geeinigt, dass zu jedem Ticket in der Entwicklung auch Dokumentation gehört. Wenn eine Entwicklerin oder ein Entwickler eine Änderung programmiert, die ein Update der Dokumentation erfordert, ist es Teil der Definition of Done für das Ticket, auch die Dokumentation anzupassen. Dafür gibt es neben Code-Review noch den weiteren Schritt Doc-Review im Ticket-Workflow. Nach anfänglicher Gewöhnungsphase haben die meisten Entwickler gemerkt, dass das oft nur fünf bis zehn Minuten in Anspruch nimmt – vorausgesetzt, die Tickets sind angemessen klein definiert – und das Dokumentieren dann gar nicht mehr so schlimm ist. Nur am Anfang Ordnung in die Dokumentation zu bringen, das war eine kleine Herausforderung.

Wenn man Dokumentation für ein lebendes System schreibt und aktualisiert, muss sie – genau wie Code – auch manchmal refaktoriert werden. Einmal im Jahr habe ich dafür einen Outlook-Termin, der mich daran erinnert, die Dokumentation durchzugehen und zu schauen, wo sich Infos doppeln, was man zusammenfassen kann, ob die Themen noch sinnvoll angeordnet sind und so weiter. Außerdem hilft ein Template, nach dem man sich richtet. Zum einen sinkt so die Wahrscheinlichkeit, dass man Themen in der Dokumentation vergisst. Zum anderen hilft es, wenn man in die Dokumentation eines anderen Projekts schaut und die Struktur schon kennt, weil sie überall dieselbe ist. Dabei muss man aufpassen, dass das Template nicht zu starr und unflexibel wird. Wir haben bei unseren Templates einige Pflichtkapitel und mehrere optionale, die wir nur bei Bedarf nutzen.

Und wenn alles, was ich bisher genannt habe, zu viel Aufwand bedeuten würde oder sich eure Kollegen einfach nicht überzeugen lassen: Benutzt wenigstens kein täterloses Passiv! Ein Satz wie "der Service XYZ wird aufgerufen" ist nicht ansatzweise so hilfreich wie "der Service ABC schickt eine verschlüsselte Anfrage mit Login-Daten an den Service XYZ".

Alexander: Die wichtigsten Punkte sind für mich einfache, wiederkehrende Strukturen in der Dokumentation und geringe Hürden, etwas beizutragen. Vorlagen wie arc42 für Systemarchitekturen oder auch die Topic Types aus dem Framework Diátaxis für Anwenderdokumentation liefern diese Strukturen, sodass man gleich mit dem Schreiben beginnen kann und dann nach und nach Lücken ausfüllt.

Technische Redakteure, die für ein Team Strukturen erstellen und mit Rat und Tat zur Seite stehen, sind ein Gewinn für jedes Projekt. Klassische Werkzeuge wie Vale helfen, den Schreibstil zu vereinheitlichen, und entlasten die technischen Redakteurinnen und Redakteure im Projekt. So haben sie Zeit, sich auf die inhaltliche Arbeit und Wissensvermittlung im Team rund um gute Dokumentation zu konzentrieren. Ansätze wie Documentation-as-Code, kurz Docs-as-Code, und Werkzeuge wie Git senken die Hürde dafür, dass Entwicklerinnen und Entwickler Inhalte beitragen. Sie können Inhalte in ihren Entwicklungsumgebungen schreiben und den gleichen Review-Workflow wie für Quellcode nutzen.

Außerdem öffnet dieses Vorgehen die Tür für einen hohen Automatisierungsgrad, sodass nach dem Schreiben und Reviewen keine weiteren manuellen Schritte bis zur Publikation notwendig sind. Allerdings tun sich Fachabteilungen und teilweise auch technische Redakteure am Anfang schwer damit, sodass bei der Einführung Unterstützung durch die Entwickler notwendig ist. Static-Site-Generatoren sind in der Regel Teil eines Docs-as-Code-Konzepts, wobei die verschiedenen Werkzeuge sehr unterschiedliche Ansätze verfolgen. Von Hugo, das mehrere Formate lesen kann und sehr individuelle Sites und Verzeichnisstrukturen ermöglicht, bis hin zu Antora, das sich auf AsciiDoc spezialisiert und klare Strukturen vorgibt, wodurch sich Autoren schnell einarbeiten können.

Für Dokumentation bevorzuge ich AsciiDoc statt beispielsweise Markdown. Während Markdown für eine README-Datei meist noch ausreichend ist, fehlen mir schnell Inhaltsverzeichnisse, Querverweise, Tabellen, Quellcode-Snippets für getesteten Code und Callouts. Mit all diesen Dingen kann AsciiDoc umgehen. Sollte ein Zielsystem unbedingt Markdown erfordern, so kann ich AsciiDoc zu Markdown konvertieren, behalte jedoch die Vorteile von AsciiDoc in meiner Schreibumgebung. Sollte bereits eine Dokumentation im Word- oder Markdown-Format vorliegen, so kann ich diese nach AsciiDoc konvertieren, im neuen Format weiterschreiben und so von den AsciiDoc-Vorteilen profitieren.

Falk: Das sind aus meiner Sicht zwei Themen. Einerseits sollte das Dokumentieren stärker Teil des Entwicklungsprozesses werden. Das heißt, die Entwicklerinnen und Entwickler müssen das Erstellen und Aktualisieren der Dokumentation als Teil ihrer Arbeit ansehen, so wie auch das Schreiben automatisierter Tests. Die Änderungen an der Dokumentation sollten durch Feedbackmechanismen, etwa in Code-Reviews, geprüft und damit das Wissen verteilt werden. Dabei hilft es, für das Schreiben der Dokumentation entwicklernahe Tools zu verwenden.

Und das ist der zweite Punkt: Die Dokumentation sollte mit leichtgewichtigen Entwicklungswerkzeugen nach dem Documentation-as-Code-Prinzip erstellt und gepflegt werden. Damit sind Markup-Sprachen wie AsciiDoc oder Markdown gemeint, ebenso wie die Ablage der Quellen in einem Code-Repository nahe beim Sourcecode, die Verwendung von Kommandozeilenwerkzeugen und die automatisierte Erstellung durch Build-Tools. Grafiken lassen sich mit in die Entwicklungsumgebung integrierten Werkzeugen wie draw.io, diagrams.net oder sogar als Textformate – mithilfe von beispielsweise PlantUML oder Mermaid.js – erstellen.

Gernot: Weniger ist mehr: Startet mal mit einem Canvas, zum Beispiel dem arc42 Canvas unter canvas.arc42.org. Damit bekommt ein Team in sechzig Minuten einen vernünftigen Startpunkt zustande. Einige unserer Teams haben dadurch sogar den Spaß an der Dokumentation wiedergefunden, weil sie in sehr kurzer Zeit ordentliche Ergebnisse erzeugen konnten.

Beschränkt euch auf wenige Bilder beziehungsweise Diagramme und verseht sie immer – ohne Ausnahme – mit einer kurzen Erklärung in Form von Text oder Tabelle. Haltet eure Dokumentation grundsätzlich schlank, Stichwort Doku-Diät: Ab und zu könnt ihr Teile, die niemand mehr benötigt, löschen. Weiterhin solltet ihr immer zuerst fragen, welche Stakeholder welches Informationsbedürfnis haben. Damit findet ihr heraus, für wen genau ihr welche Dokumentation erstellt. Das wiederum steigert unmittelbar die Motivation, diese auch zu erstellen und zu pflegen.

Schließlich gehört das Entwicklungsteam zu den wichtigsten Stakeholdern für technische Dokumentation: Wir sollten im Team gemeinsam entscheiden, was und wie wir für uns selbst dokumentieren wollen und sollen.

iX: Was sollte man auf jeden Fall vermeiden?

Charlotte: Da fallen mir direkt mehrere Sachen ein. Zum Beispiel Sätze, die allgemeingültig sind und unverändert in jedem Projekt stehen könnten. So etwas wie "Dieses Modul implementiert Business-Logik unserer Firma." Das habe ich erwartet – aber welcher Teil der Business-Logik wird implementiert? Solche Floskeln blähen die Dokumentation unnötig auf und erfordern beim Lesen zusätzliche mentale Kapazität, ohne dass sie einen Mehrwert bieten. Also: Entweder präzisieren oder raus damit!

Für mich persönlich auch ganz schlimm: Eine Dokumentation für alles. Ich finde es wichtig, sich bei Dokumentation zu fragen, für wen ich sie überhaupt schreibe. Entwickler suchen zum Beispiel andere Informationen als Projektmanager. Meiner Erfahrung nach wird der Arbeitsaufwand überschaubarer und der Nutzen größer, wenn man mehrere kleine Dokumentationen für verschiedene Zielgruppen verfasst. Dass wir ein User Manual für die Benutzerinnen und Benutzer verfassen und die Infos nicht zusammen mit den Designentscheidungen dokumentieren, ist hinlänglich bekannt. Aber eine ganz neue Idee scheint zu sein, dass zum Beispiel Infos über das Framework oder andere Technologie-Entscheidungen für den Vertrieb oder die fachliche Projektleitung irrelevant sind und daher nur in einer Dokumentation stehen sollten, die sich gezielt an die Entwickler richtet.

Eine weitere Sache sind Dokumentationen, die man wie Prosa von Anfang an lesen muss, um sie wirklich zu verstehen. Wer in die Dokumentation schaut, sucht in der Regel eine ganz spezielle Information und will sie möglichst schnell finden. Daher sollte Dokumentation so aufgebaut sein, dass man die nötigen Infos immer zusammen findet. Bei Online-Dokumentation spricht man da von "every page is page one", das heißt, jede Seite sollte so konzipiert sein, dass sie als Einstiegsseite funktioniert. Indem man auf verwandte Themen und notwendiges Vorwissen verlinkt, haben User die Möglichkeit, eigenständig das Wissen nachzulesen, das ihnen fehlt. Gleichzeitig sind die gesuchten Infos aber direkt verfügbar.

Alexander: Dokumentation kann nur dann ihren vollen Nutzen entfalten, wenn sie gelesen und verstanden wird. Dafür ist es notwendig, sie passend für die Zielgruppe zu schreiben. Daher benötigen die Autorinnen und Autoren ein zumindest minimales Verständnis der Zielgruppe, bevor sie die entsprechenden Strukturen für die Dokumentation erstellen. Dokumentation gehört für jede Iteration zur Definition of Done, wie etwa das Testen. Das Erstellen der Dokumentation sollte nicht im Nachhinein, sondern parallel zur Software geschehen. Auf diese Weise geht weniger Wissen verloren. Zudem können dann Stakeholder neue und geänderte Kapitel zeitnah lesen, Fragen stellen, das System besser verstehen und bei Bedarf Änderungswünsche rechtzeitig beauftragen.

Falk: Aus meiner Sicht sollte man Dokumentation nicht zu dogmatisch sehen, sondern pragmatisch. Wenn man grundlegende Architekturarbeit macht, also etwa Qualitätsziele erarbeitet, dann reicht aus meiner Sicht als erste Fassung der Dokumentation die einfache Protokollierung der Arbeit inklusive einer kurzen Beschreibung. Und Bilder sagen mehr als Tausend Worte. Darum sind wenige, nicht zu komplizierte Architekturdiagramme immer hilfreicher als Dutzende Seiten Text. Wenn man Architekturdokumentation als lebendige Dokumentation behandelt, bringt sie zusätzlichen Mehrwert und wird eher von allen Projektbeteiligten akzeptiert und aktuell gehalten.

Gernot (lacht): Wie viele Antworten darf ich höchstens geben? Also zuerst einmal sind Formalismus, Bloat und schlechte Tools echte Liebestöter bei der Dokumentation. Wenn Leute für die Pflege von Dokumentation erst eine Virtual Machine starten, dann darin Windows booten und dann ein fieses Tool starten müssen, werden sie sich ständig gute Ausreden überlegen, nicht zu dokumentieren.

Weiterhin halte ich Dokumentations-Sprints für ein schlimmes Anti-Pattern: Vierzehn Tage nichts anderes außer Dokumentation zu produzieren, bringt das System inhaltlich nicht voran und bereitet weder dem Product Owner noch dem Team Freude.

iX: Vielen Dank für das Interview!

Das Interview führte Maika Möbus, Redakteurin bei iX.

(mai)