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
