Hauptgedanke

Wer sagt, der Code sei die Quelle der Wahrheit über das Produkt, wird spontan so verstanden: „Die Dokumentation hat ausgedient.“ Der Gegensatz ist falsch gesetzt: Er verläuft nicht zwischen dem Code und den Dokumenten, sondern zwischen zwei Funktionen, die Dokumente erfüllen und die man nicht auseinanderhält.

Ein Artefakt, das beschreibt, sagt, was das Produkt tut: eine Support-Seite zu einer Funktion, ein Changelog, eine fachliche Spezifikation des aktuellen Zustands, eine Vertriebsunterlage darüber, was möglich ist. All das lässt sich aus dem Repository ableiten, ist also neu generierbar und damit nicht wert, gepflegt zu werden.

Ein Artefakt, das erklärt, sagt, warum: die Diskussionen und Überlegungen, die zu einer Wahl geführt haben, die Produktentscheidung und die verworfenen Alternativen, der Grund, warum eine Entscheidung eine andere ablöst. Nichts davon steht im Code, und nichts wird es dort wiederfinden. Hinzu kommt, was sich aus keinem Repository ableiten lässt, weil es von außen kommt: eine vertragliche Zusage, eine regulatorische Auflage, ein externes Dokument.

Das Sortierkriterium ist also weder die Form des Artefakts noch sein Autor, sondern die Frage, die es beantwortet. Ein und dasselbe Dokument kann übrigens beides sein und muss dann aufgeteilt statt einsortiert werden.

Die Teilung reicht bis ins Innere eines Steckbriefs. Im Steckbrief eines Produktobjekts beschreibt der Hauptteil die Wirklichkeit, so wie sie im Code steht, und wird neu generiert; der Block der Abweichungen trägt das Urteil — was von dem abweicht, was man wollte — und wird gepflegt. Die Regel, die beide getrennt hält, ist absolut und passt in einen Satz: Eine Abweichung ändert nie den Hauptteil des Steckbriefs. Ohne diese aufgeschriebene Grenze reißt die erste Neugenerierung genau den Teil mit, dessen Herstellung teuer war, denn nur er findet sich nirgendwo sonst wieder.

Ergänzt durch „Ich habe die Ontologie eines Produkts geschrieben. Dreimal dachte ich, ich wäre fertig.“ (2026-08-11).

Warum das wichtig ist

Erst diese Grenze macht die Verlagerung hin zum Code umsetzbar, ohne etwas zu zerstören. Ohne sie wählt man zwischen allem behalten — und für das Auseinanderlaufen bezahlen — und allem wegwerfen — und das Warum verlieren, dessen Fehlen erst auffällt, wenn jemand eine Entscheidung wieder aufrollt.

Sie liefert auch einen Test, den man auf jedes Produktdokument anwenden kann, bevor man über sein Schicksal entscheidet: Enthält es einen Satz, den kein Lesen des Repositorys hervorbringen könnte?

Nuancen und Grenzen

In der Theorie ist die Trennung schärfer als beim Lesen eines echten Dokuments: Eine Spezifikation vermischt ständig das erwartete Verhalten mit dem Grund, aus dem man es gewählt hat, oft im selben Satz.

Und auch was erklärt, veraltet. Eine aufbewahrte Überlegung bleibt an den Kontext ihrer Zeit gebunden; sie läuft nicht wie eine Beschreibung vom Produkt weg, sie verliert einfach an Bedeutung, ohne dass irgendetwas es anzeigt.

Offene Fragen

• Was hält in einer Organisation die Erklärungen in dem Moment fest, in dem sie entstehen, wo sie doch eher im Meeting und im Code-Review ausgesprochen als aufgeschrieben werden?