Ein neuer Entwickler sitzt vor einem Legacy-System und fragt, wo er anfangen soll. Die Antwort lautet meistens: "Frag den Thomas, der kennt das am besten." Thomas ist aber im Urlaub. Oder nicht mehr in der Firma. Oder einfach gerade in einem Meeting. Was bleibt, ist Code ohne Kontext – und ein Entwickler, der drei Tage braucht, um zu verstehen, warum ein Feld kd_nr2 heißt.

Das eigentliche Problem

In den meisten Legacy-Projekten, die ich kenne, gibt es kein Onboarding-Dokument. Es gibt vielleicht eine README, die seit 2014 nicht mehr angefasst wurde, und einen Wiki-Eintrag, den niemand mehr kennt. Das Wissen über das System steckt in den Köpfen weniger Menschen – und das ist ein Risiko, kein Feature. Das Ziel ist nicht, diese Menschen zu ersetzen. Das Ziel ist, ihr Wissen ins System zu überführen.

Welche Dokumentation wirklich hilft

Ich empfehle keine vollständige Systemdokumentation. Die wird nie fertig und ist nach einem Jahr veraltet. Was hilft, ist gezieltes Wissen an gezielten Stellen:

  • Architekturentscheidungen mit Begründung – nicht nur "wir nutzen keine ORM", sondern "wir nutzen keine ORM, weil das Datenmodell so gewachsen ist, dass jede Abstraktion mehr Probleme schafft als löst".
  • Bekannte Fallstricke – die Stellen im Code, die aussehen wie ein Bug, aber keiner sind. Oder die, die wirklich Bugs sind, aber nicht angefasst werden dürfen.
  • Datenmodell-Überblick – keine vollständige ER-Diagramm-Doku, aber eine Erklärung der wichtigsten Tabellen und ihrer Beziehungen.
  • "Was darf ich nicht anfassen und warum" – das ist oft das Wertvollste. Eine kurze Liste von Stellen, die gefährlich wirken und es auch sind.

ADRs: Leichtgewichtig und trotzdem wirksam

Architecture Decision Records (ADRs) sind kurze Textdateien, die eine einzige Entscheidung dokumentieren: was entschieden wurde, warum, und welche Alternativen verworfen wurden. Ein ADR hat keine feste Länge – manchmal sind es fünf Sätze, manchmal eine Seite. Das Format spielt keine Rolle. Was zählt, ist der Kontext, den spätere Entwickler damit bekommen. 

# ADR-007: Kein ORM für Datenbankzugriffe

## Status: Akzeptiert

## Kontext
Das Datenbankschema ist über 15 Jahre gewachsen und folgt keiner einheitlichen Konvention.
Tabellenbeziehungen sind teils implizit.

## Entscheidung
Wir verwenden direkte PDO-Abfragen statt eines ORM.

## Konsequenzen
Mehr Boilerplate, aber volle Kontrolle über SQL.
Neue Entwickler müssen SQL gut beherrschen.

Onboarding als Dokumentationsmotor

Das Beste an einem neuen Entwickler im Projekt: Er stellt Fragen, die niemand mehr stellt. Diese Fragen sind Gold. Ich bitte neue Entwickler ausdrücklich, ihre Erkenntnisse direkt zu dokumentieren – nicht am Ende der Einarbeitung, sondern während sie lernen. Ein Satz wie "Ich habe heute gelernt, dass bestellung_flag nicht für Bestellungen, sondern für interne Markierungen verwendet wird" ist wertvoller als jedes nachträgliche Dokument.

Dokumentation, die beim Schreiben schmerzt, ist zu ausführlich. Ein gutes Onboarding-Dokument passt auf zwei Seiten – und wird tatsächlich gelesen.

Fazit

Wissen, das im Kopf bleibt, geht irgendwann verloren. Wissen, das im System steht, bleibt. Das Onboarding eines neuen Entwicklers ist der beste Moment, um dieses Wissen einzufangen – weil dann jemand im Raum ist, der die richtigen Fragen stellt. Das kostet ein bisschen Disziplin. Aber es zahlt sich beim nächsten Onboarding sofort aus.