Technische Dokumentation, Die Gelesen Wird

Technische Dokumentation scheitert auf eine bestimmte und vorhersehbare Weise. Jemand schreibt in zwei ruhigen Wochen sehr viel davon, das System ändert sich, niemand pflegt sie nach, und binnen eines Jahres steht dort mit voller Überzeugung etwas Falsches. Ab diesem Punkt ist sie schlechter als gar nichts, denn wer ihr vertraut, handelt nach Angaben, die längst nicht mehr gelten.

Die übliche Reaktion darauf ist der Ruf nach mehr Dokumentation, was denselben Fehlschlag nur beschleunigt. Die nützliche Reaktion ist, weniger zu schreiben und dafür auszuwählen, was, denn der Engpass ist nicht der Schreibaufwand. Es ist die Pflege.

Der einzige belastbare Test dafür, ob ein Dokument überhaupt existieren sollte: Fällt es jemandem auf, wenn es falsch wird? Eine Deployment-Anleitung wird benutzt, und ihre Fehler zeigen sich sofort. Eine zwanzigseitige Beschreibung eines Teilsystems wird einmal gelesen, und ihre Fehler zeigen sich achtzehn Monate später, wenn jemand danach handelt. Dokumente, die niemand benutzt, verrotten lautlos, und genau die sollte man ungeschrieben lassen.

Warum sie veraltet

Drei Mechanismen, und nur einer davon ist Faulheit.

Dokumentation liegt getrennt von dem, was sie beschreibt. Eine Änderung am Code ist keine Änderung an einer Wiki-Seite, also hängt der Gleichlauf davon ab, dass jemand daran denkt. Dieses Erinnern versagt zuverlässig, und je weiter das Dokument vom Code entfernt liegt, desto schneller versagt es.

Sie beschreibt die Umsetzung statt der Absicht. Ein Dokument, das erklärt, wie eine Komponente derzeit arbeitet, wird von jedem Refactoring entwertet. Eines, das erklärt, warum die Komponente existiert und welche Randbedingung sie erfüllt, überlebt, weil der Grund sich weit seltener ändert als der Code.

Niemand ist zuständig. Dokumentation, die allen gehört, gehört niemandem, und es gibt keinen Moment, in dem ihre Richtigkeit das Problem einer bestimmten Person wäre.

Die Abhilfen folgen aus den Ursachen: nah am Code halten, Absicht statt Mechanik schreiben und jedem Dokument eine namentlich benannte verantwortliche Person geben, dazu einen Anlass, bei dem es tatsächlich benutzt wird.

Die technische Dokumentation, die Pflege verdient

Vier Dokumente decken den größten Teil des Nutzens ab. Alles andere muss sich rechtfertigen.

Ein README, das einen zum Laufen bringt. Was das hier ist, wie man es aufsetzt, wie man die Tests startet, wie man ausliefert. Es wird ständig benutzt, also treten Fehler schnell zutage. Das ist das ertragreichste Dokument in jedem Repository und zugleich jenes, das am häufigsten als unbearbeitete Projektvorlage stehen bleibt.

Eine Architekturübersicht. Welche großen Teile es gibt, wie sie miteinander sprechen und warum sie getrennt sind. Eine Seite und ein Diagramm, die die Form beschreiben statt der Details. Sie ändert sich selten und beantwortet die Frage, die sich sonst jede neue Person mühsam durch das Lesen von allem selbst zusammensetzt.

Entscheidungsprotokolle. Kurze Notizen, die eine Entscheidung, die geprüften Alternativen und den Grund festhalten. Im Fachjargon heißen sie meist Architecture Decision Records, kurz ADR. Sie werden nur ergänzt und nie aktualisiert, und sie verhindern die teuerste Art von Doppelarbeit: eine geklärte Frage schlecht neu auszufechten, weil niemand mehr die Randbedingung kennt, die sie damals geklärt hat.

Runbooks für das, was kaputtgeht. Ein Runbook ist die Ablaufanleitung für den Ernstfall: wie man die Störungen diagnostiziert und behebt, die man tatsächlich schon hatte. Geschrieben direkt nach einem Vorfall, solange er frisch ist, und erprobt beim nächsten. Ein Runbook, dem noch nie jemand gefolgt ist, ist ein Entwurf.

Beachten Sie, dass keines dieser vier Dokumente beschreibt, wie der Code funktioniert. Dafür ist der Code selbst da, und jede Prosa, die ihn verdoppelt, wird zu einer zweiten Wahrheitsquelle, die der ersten früher oder später widerspricht.

Für jemanden schreiben, der müde ist und es eilig hat

Die meiste technische Dokumentation wird unter Druck gelesen, von jemandem mit einer ganz konkreten Frage, oft außerhalb der Arbeitszeit. Schreiben Sie für diesen Leser, nicht für einen mit Muße.

Erst antworten, dann erklären. Wer nachts um zwei Ihr Runbook liest, braucht den Befehl und danach die Begründung. Kontext vor Antwort ist eine Struktur, die dem Autor passt und sonst niemandem.

Werden Sie konkret. Echte Befehle, echte Pfade, echte Beispielwerte. „Konfigurieren Sie die entsprechenden Umgebungsvariablen" ist keine Anweisung, sondern nur die Beschreibung einer Anweisung.

Sagen Sie, was schiefgehen wird. Die Fehlerbilder und wie sie sich äußern sind häufig der wertvollste Inhalt überhaupt, weil genau das der Leser gerade vor sich hat.

Halten Sie es kurz genug, dass es wahr bleibt. Jeder Satz ist eine Wartungslast. Eine Seite, die den Normalfall abdeckt und ihre eigenen Grenzen einräumt, schlägt ein Dokument, das alles abdeckt und an drei Stellen falsch ist.

Dieselbe Disziplin, die eine Seite für ein Retrieval-System zitierbar macht, macht sie auch für eine müde Kollegin benutzbar, und genau darauf läuft unser Leitfaden dazu hinaus, warum Ihre Inhalte ranken, aber nie zitiert werden, bezogen auf öffentliche Texte.

Am Leben halten

Legen Sie sie ins Repository. Ein Dokument, das mit dem Code mitreist, wird im selben Review geändert wie der Code, und das ist der einzige Mechanismus, der beide zuverlässig im Gleichlauf hält.

Prüfen Sie sie im Code-Review. Wenn eine Änderung ein Dokument falsch macht, ist das ein Review-Kommentar wie jeder andere. Das ist die wirksamste Gewohnheit, die überhaupt zu haben ist, und sie kostet nichts.

Testen Sie, was sich testen lässt. Setup-Anweisungen, die in einer Pipeline durchlaufen, hören auf, Wunschdenken zu sein. Wenn Ihr README behauptet, drei Befehle ergäben ein laufendes System, dann lassen Sie das einen Job beweisen.

Löschen Sie beherzt. Ein falsches Dokument ist schlimmer als ein fehlendes, weil man ihm vertraut. Wenn etwas veraltet ist und niemand es richten wird, nehmen Sie es heraus und notieren Sie, was dabei verloren ging.

Datieren Sie, was abläuft. Alles mit einer Versionsnummer, einem Preis oder einer externen Abhängigkeit sollte ein Datum tragen, damit ein Leser beurteilen kann, ob er ihm noch trauen darf.

Wozu das eigentlich dient

Dokumentation ist der Mechanismus, durch den Wissen aufhört, an einzelnen Personen zu hängen. Das ist der gesamte Nutzen, und deshalb ist das Argument für das Schreiben ein betriebswirtschaftliches und kein ästhetisches.

Ein System, das nur eine einzige Person ausliefern kann, hat eine Wiederherstellungszeit, die genau der Verfügbarkeit dieser Person entspricht. Eine Komponente, die niemand mehr begründen kann, wird entweder neu gebaut oder aus Aberglauben bewahrt. Beides taucht als Befund in der technischen Due Diligence auf, beides verlängert das Onboarding neuer Entwickler, und beides ist dasselbe Problem in anderen Kleidern.

Mecanik schreibt diese Dokumente in jedem Projekt als Teil der Übergabe, als Teil unserer Arbeit in der Softwareentwicklung. Das Dokument, das am Ende benutzt wird, ist fast immer kürzer als das, welches bestellt wurde.

Häufig gestellte Fragen

Warum veraltet technische Dokumentation? Weil sie getrennt vom Code liegt und der Gleichlauf davon abhängt, dass jemand daran denkt; weil sie die Umsetzung statt der Absicht beschreibt, sodass jedes Refactoring sie entwertet; und weil niemand zuständig ist, sodass ihre Richtigkeit nie das konkrete Problem einer bestimmten Person ist. Sie im Repository zu halten und sie gemeinsam mit den Codeänderungen zu prüfen, behebt alle drei Ursachen auf einmal.

Welche Dokumentation sollte ein Softwareteam pflegen? Vier Dinge decken den größten Teil des Nutzens ab: ein README, das das System zum Laufen bringt, eine einseitige Architekturübersicht zu Form und Begründung, nur ergänzte Entscheidungsprotokolle darüber, warum etwas so entschieden wurde, und Runbooks für Störungen, die Sie tatsächlich schon hatten. Beschreibungen davon, wie der Code funktioniert, stehen nicht auf dieser Liste.

Was ist ein Entscheidungsprotokoll? Eine kurze Notiz, die eine Entscheidung, die geprüften Alternativen und den Grund für die Wahl festhält. Weil sie einen Zeitpunkt festhält statt eines aktuellen Zustands, muss sie nie aktualisiert werden, und sie verhindert, dass geklärte Fragen von Leuten schlecht neu ausgefochten werden, die die entscheidende Randbedingung längst nicht mehr kennen.

Wie sollte technische Dokumentation geschrieben werden? Für jemanden, der müde ist, unter Druck steht und genau eine bestimmte Sache sucht. Zuerst antworten und danach erklären, echte Befehle und echte Pfade statt Beschreibungen davon verwenden, sagen, was schiefgeht und wie es aussieht, und alles kurz genug halten, dass es wahr bleibt.

Sollte veraltete Dokumentation gelöscht werden? Ja, wenn niemand sie richten wird. Ein falsches Dokument ist schlimmer als ein fehlendes, weil ein Leser ihm vertraut und danach handelt. Löschen Sie es und notieren Sie, was verloren ging, und datieren Sie alles, was eine Versionsnummer, einen Preis oder eine externe Abhängigkeit enthält, damit Leser selbst urteilen können.