Irgendwo in einem deutschen Unternehmen liegt gerade ein Confluence-Space mit 847 Seiten. Davon sind 12 aktuell. Die anderen 835 beschreiben Systeme die es nicht mehr gibt, Prozesse die niemand mehr so macht, und Entscheidungen die vor drei Reorganisationen getroffen wurden.
Das ist keine IT-Dokumentation. Das ist ein digitales Archiv für schlechtes Gewissen.
Warum dokumentieren wir überhaupt?
Die ehrliche Antwort: weil wir Angst haben. Angst dass jemand geht und das Wissen mit ihm. Angst dass wir in sechs Monaten nicht mehr wissen warum wir das damals so gebaut haben. Angst vor dem Audit. Angst vor der Übergabe.
Das sind valide Gründe. Aber sie führen zur falschen Antwort: alles dokumentieren. Immer. Vollständig. Mit Template. Das Ergebnis kennt jeder: Dokumentation die veraltet ist bevor die Tinte trocken ist, weil Änderungen nie den Weg dorthin finden.
Was Dokumentation wirklich kosten kann
Dokumentation ist nicht kostenlos. Jede Stunde die ein Entwickler damit verbringt Dinge aufzuschreiben die im Code stehen, ist eine Stunde die er nicht baut.
Und dann kommt das eigentliche Problem: Dokumentation muss gepflegt werden. Ein System ändert sich. Das Hosting wandert. Eine Abhängigkeit fällt weg. Wer aktualisiert die Doku? Niemand. Weil es keine Kapazität gibt, kein Prozess, keine Verantwortung. Also bleibt sie stehen, wird älter, und wird zuverlässiger falsch.
Falsche Dokumentation ist schlimmer als keine Dokumentation. Sie gibt Sicherheit die nicht existiert.
Wann man keine Doku braucht
Wer Code lesen kann, braucht oft keine separate Dokumentation. Guter Code ist selbst dokumentierend. Klare Variablennamen, kleine Funktionen, verständliche Struktur, das ist die Dokumentation.
Das gilt nicht für alle. Aber es gilt für mehr Situationen als die meisten Teams zugeben.
README.md: Der Standard der sich durchgesetzt hat
Zum Glück hat sich für Code eine pragmatische Lösung etabliert: die README.md. Direkt im Repository, genau dort wo der Code liegt. Wer das Projekt öffnet, sieht sie sofort.
Kein separates Wiki. Kein Confluence-Space der drei Klicks entfernt ist. Kein Tool das man sich extra einloggen muss. Die Dokumentation lebt dort wo der Code lebt, und wird damit automatisch mit jedem Commit sichtbar gehalten.
Und noch ein Schritt weiter: Wer README.md-Dateien und Code-Repositories direkt ins Firmenwissen eines LLMs einbindet, ermöglicht etwas Praktisches. Das LLM kann dann nicht nur für Entwickler erklären was der Code tut, sondern auch für Nicht-Techniker die Logik dahinter verständlich machen. Produktmanagement fragt was ein bestimmter Prozess macht, und bekommt eine Antwort in Klartext, nicht in Stacktraces.
Was wirklich dokumentiert werden muss
Nicht alles braucht Doku. Aber manches braucht sie unbedingt. Der Unterschied liegt nicht im Code, sondern im Kontext.
Was bleibt: Wo liegt das Hosting? Wer hat Zugriff auf was? Welche externen Dienste sind angebunden und wer zahlt dafür? Was passiert wenn System X ausfällt? Wer wird dann angerufen?
Das sind keine technischen Fragen. Das sind operative Fragen die jedes Unternehmen beantworten können muss, unabhängig davon ob jemand krank ist, in Urlaub oder gekündigt hat.
Kurz: Dokumentiere nicht den Code. Dokumentiere den Kontext. Wo liegt was. Wer owned was. Was passiert wenn etwas schiefgeht.
Der LLM-Trick den kaum jemand nutzt
Ein Entwickler der seinen Code in einen LLM wirft und fragt „erkläre mir was dieser Code tut und schreib eine Readme“ bekommt in drei Minuten etwas das früher eine Stunde Arbeit war.
Das verändert die Kalkulation komplett. Der Aufwand für technische Dokumentation ist um den Faktor 10 gesunken. Wer das ignoriert, bezahlt noch den alten Preis für ein längst günstigeres Produkt.
Was bleibt
IT Dokumentation ist kein Selbstzweck. Sie ist ein Werkzeug. Und wie jedes Werkzeug ist sie nützlich wenn man sie richtig einsetzt, und Ballast wenn man sie für alles einsetzt.
Drei Fragen die jedes Team beantworten können sollte: Wo liegt das Hosting und wer hat Zugriff? Was sind die kritischen externen Abhängigkeiten? Wen ruft man an wenn etwas brennt?
Alles andere ergibt sich, aus dem Code, aus dem Kontext, oder aus einem LLM der beides zusammenfasst.
— Robert
