Welche Dokumentation Entwickler brauchen – und warum sie durch KI noch wichtiger wird

Lange habe ich mich gefragt, wie viel Dokumentation ein Softwareprojekt eigentlich braucht. Zu wenig Dokumentation führt dazu, dass Wissen immer wieder neu erarbeitet werden muss. Zu viel Dokumentation kostet Zeit und veraltet. In meinem aktuellen Projekt haben wir für uns einen ziemlich guten Mittelweg gefunden: Die Dokumentation ist überschaubar, wird tatsächlich genutzt – und seit wir KI beim Entwickeln einsetzen, ist sie noch einmal deutlich wertvoller geworden

Ist mehr immer besser?

Haben ist zwar besser als brauchen, aber ich bin kein Freund davon, alles zu dokumentieren. Dokumentation, die niemand liest und die nach einem Jahr veraltet ist, hilft niemandem. Entscheidend ist, genau das Wissen festzuhalten, das sich nicht ohne Weiteres aus dem Code ableiten lässt. Und: Veraltete Dokumentation kann in Zeiten von KI sogar schädlicher sein als gar keine Dokumentation. Eine KI kann nur schwer beurteilen, ob eine vermeintlich verbindliche Vorgabe längst überholt ist, und verwendet sie unter Umständen als gültigen Kontext.

Warum fünf Sätze Dokumentation Gold wert sein können

Bei meinem Kunden gehen aktuell ein paar neue Anwendungen produktiv. Dazu werden diese zwingend immer einem Penetrationstest unterzogen. Letztens hat mich der Abteilungsleiter meines Kunden gefragt, wie wir damals mit dem CSRF Finding des Penetrationtests umgegangen sind. Da dieses für die Anwendung an der ich aktuell mitarbeite schon über zwei Jahre zurücklag, konnte ich mich nicht mehr erinnern. Aber zum Glück haben wir kurz dokumentiert, wie die Anwendung abgesichert ist. Dort war dokumentiert, warum unter den für die Anwendung geltenden Voraussetzungen keine zusätzliche CSRF -Schutzmaßnahme notwendig war und unter welchen Annahmen die Security-Abteilung diese Entscheidung freigegeben hatte.

Wie soll sich das System fachlich verhalten

Es ist schon sehr gut, wenn die Fachlichkeit dokumentiert ist. Eine Dokumentation nur in den Stories / Tickets reicht nicht aus. Stories und Tickets sind für mich eher historische Artefakte: Sie erklären, warum eine Änderung entstanden ist. Beispielsweise dass die Validierung eines Feldes angepasst werden muss. Die fachliche Dokumentation beschreibt dagegen, wie das System heute funktionieren soll. Ich habe schon Projekte erlebt, wo dieselben Codestellen mehrmals komplett umgebaut wurden da es so wie es ursprünglich gebaut war, dann doch nicht so gut beim Kunden ankam. So ist es dann schwer zu erkennen, ob der Codeschnipsel noch da sein sollte oder ob es noch aus „historischen Gründen“ von früher so ist. Hier hilft es wenn man eine Doku hat die beschreibt wie es jetzt sein sollte statt dieses mühsam aus den vielen Tickets zusammenzusuchen, die in dem Bereich bearbeitet wurden. Die fachlichen Vorgaben sollten somit als Single Source of Truth angesehen werden. Wir verlinken in den Stories / Tickets immer die fachliche Dokumentation. So kommt man dann von dem Commit (der einen Link auf die Story beinhaltet) über eben diese auf die aktuelle fachliche Dokumentation.

Bei den Projekten, an denen ich für meinen aktuellen Kunden arbeite, handelt es sich um Backend-for-Frontend-Anwendungen. Dort bestehen die Anwendungen jeweils aus einem Angular-Frontend und einem Java-Backend. Das Java Backend ruft dann die eigentlichen Backends im Unternehmen auf und bietet eine REST-Schnittstelle an, die für das Angular-Frontend optimal ist.  Als fachliche Dokumentation ist hier vor allem folgendes interessant:

  • Was für fachliche Felder gibt es in der Anwendung
  • Was für fachliche Regeln haben diese Felder:
    • Validierungslogiken
    • Default-Werte
    • Datenmanipulation des Feldes. Wird es bspw. zurückgesetzt wenn sich ein anderes Feld ändert
    • Steuerungslogiken: Also wann ist das Feld sichtbar, wann kann man es editieren
    • Welchen Typ hat es
    • Mit welchem Label wird es angezeigt
  • Wie soll die Anwendung aussehen (Storybook). Hier kann man dann auch optimalerweise auf die fachlichen Dokumentationen verlinken.
  • Mapping-Definition der externen Schnittstellen auf die internen Felder

Ich bin in dem Projekt noch vor den KI-Zeiten gestartet. Jetzt in den KI-Zeiten zahlt sich diese Dokumentation aber extrem aus. Wir haben bspw. eine Anleitung für die KI geschrieben, was dazugehört ein neues Feld einzubauen – wir nennen so etwas bei uns Skill. Da diese fachliche Dokumentation sehr genaue Vorgaben macht und sich die fachlichen Begriffe auch im Code wiederfinden (Ubiquitous Language) kann die KI diese sehr gut umsetzen. Der KI geben wir anschließend nur noch die Seite mit den Fachvorgaben als Kontext. Zusammen mit unserem Skill kann sie daraus eine Änderung von der Domänenschicht bis ins Frontend weitgehend eigenständig umsetzen. Review und Tests bleiben natürlich weiterhin Teil des Entwicklungsprozesses. Und selbst wenn man hin und wieder etwas nachpolieren muss, so sind hier doch deutliche Geschwindigkeitsvorteile zu erreichen.

Architektur:

Die Aufgabe von uns Entwicklern ist es, die Architektur zu dokumentieren. Ich kann hierfür das  arc42 Format empfehlen. Ich kenne bislang keinen, der dort wirklich jedes Kapitel ausgefüllt hat. Aber es gibt einem immerhin eine gute Struktur vor. Grundsätzlich sollte aber immer mindestens Folgendes vorhanden sein.

  • Einführung & Ziele: Die Top 3 Qualitätsziele sind ja meistens bekannt (ist bspw. Wartbarkeit besonders wichtig, oder eher Performanz?). Selbst wenn diese nicht explizit definiert wurden. so haben zumindest die Entwickler doch implizite Annahmen. Diese kann man daher auch kurz aufschreiben. Macht man meistens einmal am Anfang des Projektes.
  • Randbedingungen: Gibt es irgendwelche Vorgaben von außen wie die Architektur auszusehen hat? Im Enterprise Umfeld gibt es meistens eine Meta-Architektur an die sich alle Services im Unternehmen halten sollten. In diesem Fall kann man diese in diesem Bereich verlinken. Dann findet man diese als Neueinsteiger auch schnell.
  • Im Kapitel Kontext & Abgrenzung
    • Hier sollte man dokumentieren, von welchen anderen Services das Projekt abhängt. Hier macht es Sinn u.a. folgendes aufzulisten:
      • Ansprechpartner
      • Doku für den Service
      • Die Urls pro Umgebung
      • Wie ist der Service abgesichert? Muss man ihn bspw. mit einem JWT aufrufen? Wenn ja, was muss dieser beinhalten?
    • Wenn es noch Projekte gibt, die von uns, also dem Service abhängen und von denen wir wissen, dann macht es auch Sinn, diese in solchen Steckbriefen zu dokumentieren. Dann weiß man zumindest, welche Teams man benachrichtigen muss. Das ist bspw. praktisch wenn man einen komplizierteren Umbau vorgenommen hat, der im besten Fall kompatibel war, aber wo man dann doch lieber die anderen Teams verifizieren lassen möchte, dass deren Anwendung noch geht.
  • Querschnittliche Konzepte: Die typischen Entwicklerdokus. Also bspw.:
      • Wie ist der Service abgesichert. Man muss jetzt hier nicht Spring Security neu erklären, aber das Spezielle für das Projekt kann man schon aufschreiben. Bspw. warum man die CSRF Prüfung wieder ausgebaut hat, siehe den Anfang dieses Artikels.
      • Wie funktioniert die Message Queue Anbindung, wie ist diese bspw. in Kubernetes konfiguriert.
      • Hat das Projekt einen Reverse Proxy und wie ist der konfiguriert
      • Wie funktioniert die SSL/TLS Terminierung und wie ist die konfiguriert
      • Wo bekommt man die Zertifikate her
      • Sachen, die wir mal experimentell gebaut haben, die wir aber wieder verworfen haben und wo wir nicht sicher sind, ob sie nicht doch wieder kommen. Man kann sich die Lösung dann als Markdown von der KI zusammenfassen lassen und dann hat man sie hier liegen.
      • ….
  • Risiken & technische Schulden:
      • Meistens gibt es in Projekten bekannte Probleme, die immer mal wieder zu Alerts führen. Man weiß ggf. noch nicht, woran das liegt oder das Problem lässt sich nicht so einfach fixen oder tritt nur selten auf. Dann kann man diese hier inkl. Beispiel-Logmeldung aufführen. Muss bei dem Fehler dann irgendwas getan werden, kann das auch hier beschrieben werden.
      • Architektur-Reviews die man durchgeführt hat. Ich habe bspw. gute Erfahrungen mit LASR als Format gemacht da sich dieses relativ einfach und mit wenig Aufwand durchführen lässt. Das Ergebnis kann man dann hier ablegen.
  • Die Architekturentscheidungen sollten in Form von ADRs dokumentiert sein
  • Glossar. Je nach Kontext kann derselbe Begriff unterschiedliche Dinge bedeuten. In diesem Fall macht es Sinn, dieses einmal aufzuschreiben.

Diese Doku wird bei uns von den Entwicklern gepflegt. Wenn man lange über ein Thema diskutiert oder an einer komplizierten Lösung gearbeitet hat, sollte man das Ergebnis direkt dokumentieren – solange die Details noch präsent sind. Davon profitiert man Monate später selbst – und inzwischen auch die KI, der man diese Dokumentation als Kontext geben kann. Wenn man bei der Doku dann immer am Ball bleibt dann ist sie auch mit relativ wenig Aufwand wartbar.

Sonstige Themen (die aber nicht weniger wichtig sind)

  • Eine Linkliste mit allen wichtigen Links für das Projekt:
    • Git Repo
    • bei Webanwendungen Links, unter denen die Anwendung erreichbar ist
    • Wo ist das deployed? Also Links zu OpenShift / Kubernetes usw.
    • Wie kommt man auf die Logs drauf
    • Build Pipeline
    • Welche Dashboards gibt es
    • ….
  • Eine Liste der Ansprechpartner. Dieses ist meistens wichtig für andere Teams die mit einem kommunizieren wollen
  • Besprechungsnotizen inkl. Datum, damit klar ist ob diese ggf. veraltet sind. Diese veralten dann teilweise aber doch. Daher macht es manchmal dann auch einfach Sinn, diese in einem ADR zu überführen oder einfach nach der Besprechung die entsprechende Fachvorgabe oder Architektur-Dokumentation zu überarbeiten.
  • Testbenutzer / Rollen sofern vorhanden und wo man ihre Zugangsdaten herbekommt bzw. wie man diese anlegt.
  • How-tos:
    • Wie muss man das Projekt aufsetzen
    • Best Practices
    • Wie geht man vor um neue Zertifikate zu beantragen (sofern das nicht automatisiert ist …)
    • Wie kann man XYZ testen …
    • ….

Wo liegt die Dokumentation

Entscheidend ist für mich weniger, ob die Dokumentation in Wiki, Git oder einem anderen System liegt. Entscheidend ist, dass sie leicht auffindbar, aktuell und für die Werkzeuge erreichbar ist, die damit arbeiten sollen.

Die Dokumentation liegt bei meinem aktuellen Kunden im Wiki. Das hat den Vorteil, dass die Dokumentation relativ einfach durchsuchbar ist und auch relativ einfach verlinkt werden kann. Mein Team betreut bspw. mehrere Systeme bei dem Kunden, die aber relativ gleich funktionieren. Wir haben aber ein Hauptsystem. Teilweise schreiben wir dann die Dokumentation nur in dem Hauptsystem und in dem Nebensystem beschreiben wir in der Dokumentation dann nur Neues oder wenn etwas abweicht.

Für die KI wäre es aber sicherlich einfacher, wenn die Dokumentation im Code liegen würde. Hier liegen bei uns im Projekt dann aber nur die Skills / Anleitungen für die KI (u.a. was für das Hinzufügen eines neuen Feldes getan werden muss) oder die Readme die dann auf die Dokumentation im Wiki verlinkt.

Ich würde diese dann immer wieder im Wiki pflegen. Optimalerweise hat die KI dann auch Zugriff darauf. Bei meinem Kunden ist das aktuell aus Sicherheitsgründen zwar nicht der Fall. Wir exportieren die Seite dann aber als HTML und geben sie so dann der KI als Kontext mit.

Muss das so?

Nein natürlich nicht. Nichts ist in Stein gemeißelt. Nur für solche Projekte, wo man REST-APIs schreibt die hauptsächlich von einem Frontend konsumiert werden (und davon habe ich in den letzten Jahren einige gesehen) fand ich obige Informationen praktisch. Andere Arten von Services mögen auch andere Arten von Dokumentation benötigen. Auch mag man die Informationen anders ablegen.  Bspw. könnte die oben genannte Linkliste mit OpenShift Links usw. genauso in dem Kapitel „Verteilungssicht“ nach arc42 abgelegt werden. Da wurde sich im Team aber dagegen entschieden. Wichtig ist vor allem, dass die nützlichen Informationen dokumentiert und aktuell sind sowie leicht gefunden werden. Da wir uns im Team darauf geeinigt haben, dass es immer diese zentrale Linkliste gibt, passt das für mich so.

Schlusswort

Als ich damals in dem Projekt gestartet bin, war ich überrascht, wie viel Wert auf Dokumentation gelegt wurde. Ich hatte meiner Meinung nach auch schon immer viel Wert drauf gelegt, aber mein aktuelles Team hat das noch einmal getoppt. Das war damals noch vor KI-Zeiten. Als wir dann anfingen mit KI-Unterstützung zu entwickeln, hat sich diese Dokumentation dann stark bezahlt gemacht, da man zusammen mit dieser dann ziemlich schnell fachliche Features umsetzen konnte. Aber auch unabhängig davon war diese Dokumentation in der Vergangenheit praktisch, da sich schnell neue Teammitglieder einarbeiten konnten und man Rückfragen von anderen Teams (Wie habt ihr Xyz gelöst?) mit einem Link auf die Doku beantworten konnte.

Früher war die Dokumentation „nur“ eine Investition in die Zukunft, damit man in der Zukunft leichter nachvollziehen konnte, was man heute getan hat. Auch da hätte sich (aktuelle) Dokumentation schon rentiert. Aber in Zeiten von KI ist sie noch einmal wichtiger geworden, weil sie der KI den Kontext liefert, den sie braucht, um sinnvoll an einem bestehenden System mitzuarbeiten.