Auf Slack trifft eine Frage ein: Kann das Produkt das hier, für diesen Kunden, in genau diesem Fall?

Keine abstrakte Frage. Kein Nachdenken über die Vision für die nächsten fünf Jahre. Eine Frage aus der Praxis, die innerhalb einer Stunde beantwortet sein muss. Also öffnet jemand eine Testumgebung, stellt den Fall nach, prüft. Eine halbe Stunde. Zweimal bezahlt: von der Person, die sucht, und von der, die sie unterbricht.

Das ist kein Dokumentationsproblem. Dokumentation gibt es, und sie ist aktuell. Das Problem ist, dass das, woraus das Produkt besteht — die Objekte, die es verarbeitet, die Regeln, die sie beherrschen, die Wörter, mit denen man darüber spricht —, nirgends in einer abfragbaren Form aufgeschrieben ist. Es existiert an zwei Orten: im Code, den einige wenige lesen können, und in den Köpfen genau dieser Leute.

Also habe ich versucht, es aufzuschreiben. Das Ergebnis liegt vor: mehrere Dutzend beschriebene Objekte, einige Hundert Regeln, ebenso viele Verknüpfungen zwischen ihnen. Dieser Artikel erzählt, wie ich dahin gekommen bin — und vor allem, was ich unterwegs verpasst habe, denn das ist der Teil, der sich übertragen lässt.

Drei Vorbemerkungen.

Die erste: Dieser Erfahrungsbericht handelt vom Bau des Referenzwerks, nicht von seiner Nutzung. Es existiert, es ist gemessen, es hat seine ersten Nebenprodukte hervorgebracht. Aber die Nutzungsphase hat noch nicht begonnen. Über den Return on Investment kann ich also nichts behaupten. Wer dir an dieser Stelle eine Zahl verkauft, erfindet sie.

Die zweite: Die Beispiele stammen aus einem fiktiven Fall — eine Firma, die ein SaaS-Verwaltungssystem herausgibt, ein ERP, mit seinen Kunden, Aufträgen, Positionen und Rechnungen. Was sich von einem Produkt auf das andere überträgt, sind nicht meine Funde, sondern die Art von Problem, die man findet: ein Zustand, der überall neu berechnet und nirgends definiert wird, eine Regel, die nur auf einer Seite greift, ein Wort, das die Kunden benutzen und das Produkt nicht kennt. Diese drei hast du auch. Die Einzelheiten des Falls interessieren dagegen niemanden.

Die dritte: Es ist lang, eine halbe Stunde Lesezeit. Es ist ein Bericht, kein Blogbeitrag — ich wollte lieber alles sagen als mich kurz fassen. Wenn du nur einen Abschnitt liest, nimm „Drei Abschlusskriterien. Dreimal falsch.“: der Rest ist der Kontext darum herum. Die Anhänge nützen nur denen, die diese Arbeit nachmachen wollen.

Eine Ontologie ist kein angereichertes Glossar

Das Wort ist eine Falle. Für die einen klingt es nach Philosophie, für die anderen nach einem Fachgebiet mit komplizierten Werkzeugen, für die meisten nach gar nichts. Also klären wir es sauber.

Eine Ontologie ist die ausdrückliche und strukturierte Beschreibung dessen, woraus ein Gegenstandsbereich besteht: - die Typen von Objekten, die es gibt, - was sie kennzeichnet, - was sie verbindet, - was über sie wahr ist, - die Wörter, mit denen man sie bezeichnet.

Auf eine Software angewandt, beantwortet sie fünf Fragen. Jede entspricht etwas, das man aufschreibt, und jede hat einen gelehrten Namen, den du danach nicht mehr brauchst:

Im weiteren Artikel sage ich, um die gelehrten Begriffe zu vermeiden, „Objekte“, „Eigenschaften“, „Verknüpfungen“, „Regeln“ und „Wörter“. Gemeint ist dasselbe.

Diese fünf Kästchen wirken auch als Filter: Was in keines passt, hat im Referenzwerk nichts zu suchen.

Warum noch ein Dokument

Es gab bereits ein Glossar, ein Datenbankschema, Dokumentation. Das Glossar definiert Wörter, eines nach dem anderen. Das Schema ordnet Daten nach technischen Zwängen, nicht nach dem Fach. Die Dokumentation erzählt, für menschliche Leser.

Was sie von einer Ontologie unterscheidet, lässt sich auf einen Punkt bringen: Die Verknüpfungen zählen dort genauso viel wie die Definitionen. Ein Objekt, das für sich allein beschrieben wird, sagt wenig. Dasselbe Objekt, mit fünf anderen über präzise Verben verknüpft — erteilt von, enthält, fakturiert in —, beschreibt ein Produkt.

Was sie zusammenführt

Ein und dasselbe Objekt trägt in einem Unternehmen drei Namen. Nehmen wir den Kundenauftrag:

Diese drei Vokabulare entwickeln sich getrennt, und der Unterschied zwischen ihnen ist eine wertvolle Information. Das Referenzwerk bewahrt ihn auf: das offizielle Wort, die Wörter der Kunden und die, die unterwegs aufgegeben wurden. Genau das erlaubt es, einen Satz eines Nutzers in ein Objekt des Produkts zu übersetzen — und umgekehrt.

Was ich nicht gemacht habe

Es gibt sehr gelehrte Arten, das alles zu tun: eigene Sprachen, Werkzeuge, die aus den gegebenen Regeln Schlüsse ableiten, und die passenden Normen dazu. Das ist ein echtes Fachgebiet, und dorthin bin ich nicht gegangen (unter anderem, weil mir die Kenntnisse fehlen).

Ich habe mit dem angefangen, was ich sicher beherrsche: ein Steckbrief pro Objekt, in einer Textdatei. Ein Titel, ein paar Felder, Verknüpfungen zu den anderen Steckbriefen. Nichts, was ein Texteditor nicht öffnen könnte. Solange ich nicht weiß, wozu das Referenzwerk dienen wird, weiß ich auch nicht, wie viel Strenge ich brauche — und einfach anzufangen und es später komplizierter zu machen, kostet immer weniger als der umgekehrte Weg.

Der Code wurde zur Quelle der Wahrheit. Der Sinn blieb draußen.

Rund um dieses Produkt wird ein wachsender Teil dessen, was das Produkt beschreibt, aus dem Code neu erzeugt. Die Überlegung dahinter ist einfach: Die Wahrheit eines Produkts ist das, was läuft, nicht das, was geplant war.

Dieser Wechsel schafft eine ganze Arbeit ab — nämlich, von Hand Dokumente aktuell zu halten, die etwas anderes beschreiben als die Wirklichkeit. Das ist ein erheblicher Gewinn, und ich würde ihn immer noch verteidigen.

Aber er verschiebt das Problem.

Was der Code nicht hergibt

Der Code legt fest, wie das Produkt funktioniert. Der Sinn dagegen entsteht darüber.

Nehmen wir den Auftrag und seinen Zustand. Der Code gibt die Struktur her: hier die Felder, hier die möglichen Werte. Vier Informationen machen ihn erst wirklich brauchbar, und keine davon steht dort:

• die Regel — ein fakturierter Auftrag nimmt keine Position mehr auf. Das Produkt setzt sie durch, aber die Regel ist nirgends aufgeschrieben: die Prüfung ist über fünf Dateien verstreut, und jede erledigt nur ein Stück davon. Um sie in einem Satz auszusprechen, muss man alle fünf gelesen haben;
• die Sonderfälle — ein Eilauftrag ist ein Auftrag, mit zusätzlichen Auflagen;
• das Vokabular — die Nutzer sagen „Geschäft“, und ein anderer Begriff wurde vor drei Jahren aufgegeben;
• die Reichweite — das Produkt umfasst zwei Anwendungen, die ich A und B nenne, und jede legt einen eigenen Sinn hinter dasselbe Wort.

Zusammengenommen verwandeln diese vier Informationen eine Datenstruktur in eine Produktbeschreibung. Genau das ist der Inhalt eines Steckbriefs. Und keine davon liegt am selben Ort: Sie verteilen sich auf den Kern des Codes, die Datenbank, die Oberflächen und die Übersetzungen.

Die eigentlichen Kosten fallen woanders an

Die Frage vom Anfang ist nur ein Fall unter vielen. Alles, was das Produkt jemandem beschreibt, ist ein Nachbau, jedes Mal neu, parallel, in jeder Abteilung: die Dokumentation, die Antworten auf Ausschreibungen, die Einarbeitung neuer Leute, die Sprache des Supports. Jeder fängt wieder beim Code an oder beim Gedächtnis von irgendjemandem.

Genau diese Ausgabe soll verschwinden. Sie taucht in keinem Budget auf, weshalb wir sie seit Jahren bezahlen, ohne sie zu sehen.

Eine KI kann nicht nachfragen. Sie rät.

Bis jetzt wurde mündlich weitergegeben, was das Produkt wirklich ist. Man fragte die richtige Person, bekam die Regel und ging wieder. Das Modell des Produkts lebte in einigen wenigen Köpfen, und das funktionierte, weil man immer an eine Tür klopfen konnte.

Eine KI klopft an keine Tür.

Wenn man ihr eine Weiterentwicklung anvertraut, beschreibt man sie in ein paar Sätzen. In unserem Kopf steckt ein vollständiges Modell: was ein Auftrag ist, welche Zustände er durchläuft, was verboten ist und ab wann. Der Agent hat nur unsere paar Sätze, dazu das, was er im Code lesen kann. Den Rest füllt er auf — plausibel, stimmig und manchmal falsch.

Der Unterschied zwischen dem, was wir wollten, und dem, was wir zurückbekommen, ist genau der Teil unseres mentalen Modells, den wir nicht aufgeschrieben haben.

Ein Referenzwerk ist dieses aufgeschriebene mentale Modell. Es einem Agenten zu geben, macht ihn nicht klüger: Es hindert ihn daran, dort zu erfinden, wo eine Regel existiert. Daraus folgen drei Anwendungen, und das sind die, die mich interessieren.

Eine Weiterentwicklung anfordern, ohne das Produkt neu zu erklären. „Füge einen Rabatt auf Aufträge hinzu.“ Mit dem Referenzwerk im Kontext weiß der Agent, dass ein fakturierter Auftrag keine Position mehr aufnimmt, dass ein Rabatt eine Obergrenze hat und dass „Auftrag“ auch Eilaufträge und Daueraufträge umfasst. Ohne das Referenzwerk entdeckt er eines dieser drei Dinge beim Gegenlesen — im besten Fall.

Schneller analysieren. Einen Bug zu untersuchen beginnt immer damit, das Modell des betroffenen Bereichs neu zusammenzusetzen. Dieser Nachbau wird jedes Mal wiederholt, von jeder Person und von jedem Agenten. Einmal aufgeschrieben, liest er sich in wenigen Sekunden. Und einige Hundert Steckbriefe passen in einen Kontext, während Tausende Code-Dateien das nicht tun: Der Agent liest, was nötig ist, statt aufs Geratewohl zu wühlen.

Tests schreiben und Meldungen entscheiden. Eine Regel ist eine überprüfbare Aussage. „Ein fakturierter Auftrag nimmt keine Position mehr auf“ ist ein Test, so wie er dasteht, in der Fachsprache formuliert. Einige Hundert Regeln sind ebenso viele Testkandidaten, die niemand mehr aus dem Code ableiten muss. Und vor einer Kundenmeldung wird die Frage mechanisch: Widerspricht das einer aufgeschriebenen Regel — dann ist es ein Bug; oder ist es eine Regel, die nie jemand festgelegt hat — dann ist es eine Produktentscheidung, kein Mangel. Heute fällt dieses Urteil aus Erfahrung, durch die Person mit der längsten Zugehörigkeit im Team.

Nichts davon ist gemessen, wie in der Vorbemerkung gesagt. Der Mechanismus scheint mir solide — man streicht den geratenen Anteil —, aber ich habe den Test nicht gemacht. Den werde ich machen: rund dreißig Anfragen nehmen, die Hälfte mit dem Referenzwerk im Kontext bearbeiten und die andere ohne, dann die aufgewendete Zeit und die Zahl der Nacharbeiten vergleichen. Solange das nicht geschehen ist, ist dieser Abschnitt eine Erwartung, kein Ergebnis.

Die Methode: skizzieren, um zu wissen, wonach man sucht

Gleich zu Beginn stellt sich ein Dilemma. Ohne ein Modell, und sei es grob, weiß man nicht, welches Material man einsammeln soll — und geht an wichtigen Informationen vorbei, ohne es zu merken. Ohne Material weiß man nicht, welches Modell trägt.

Iterieren, nicht in Phasen zerlegen. Man skizziert gerade genug, um zu wissen, wonach man sucht, sucht, und nimmt das Modell mit dem Gelernten wieder auf. Eine Auflage zieht sich durch dieses Hin und Her: Was man einsammelt, wird in der einfachsten möglichen Form abgelegt, und immer mit dem Hinweis, woher es stammt. Eine Änderung am Modell darf nie dazu zwingen, schon Gesammeltes erneut zu holen.

Wo anfangen: rund zwanzig Fragen, die uns schon gestellt wurden

Ein Produkt hat Dutzende Bereiche — die Fakturierung, den Einkauf, die Zugriffsrechte, die Suche, die Benachrichtigungen. Mit welchem anfangen? Die theoretische Antwort ist bekannt: Man schreibt zuerst die Fragen auf, die das Referenzwerk später beantworten können muss, und sie stecken das Gelände ab. Das Problem ist, dass Fragen, die man am Schreibtisch in einem Besprechungsraum aufschreibt, immer dem ähneln, was man für wichtig hält.

Also habe ich sie nicht aufgeschrieben. Ich habe sie mir geholt.

Die Produktfragen, die bei uns eintreffen, werden mitsamt ihrer Antwort archiviert. Ich habe sie alle noch einmal gelesen und dann zu rund zwanzig allgemeinen Fragen verdichtet. Keine stammt aus meiner Fantasie: Jede deckt eine Menge tatsächlich gestellter Fragen ab.

Auf das fiktive ERP übertragen, sehen sie so aus:

• Welche Zustände hat ein Auftrag, und welche Übergänge zwischen ihnen sind erlaubt?
• Was lässt sich noch stornieren, und ab welchem Moment nicht mehr?
• Was ist der Saldo eines Kunden, und durch welche Bewegungen verändert er sich?
• Wem gehört ein automatisch erzeugter Auftrag, und was wird aus ihm, wenn diese Person die Firma verlässt?
• In welchen Fällen sieht ein Nutzer einer Tochtergesellschaft die Aufträge einer anderen Tochtergesellschaft?
• Wie nennen die Nutzer den Auftrag, und in welchen Sprachen?

Das sind keine eleganten Fragen. Es sind die, die jemanden eine halbe Stunde kosten, mehrmals im Monat.

Was sie sofort liefern: die Reihenfolge der Arbeit. Jede Frage berührt einen oder mehrere Bereiche des Produkts; man muss nur zählen. Mehr als die Hälfte der Fragen traf denselben Bereich — er wurde der erste. Der Rest verteilte sich auf zwei weitere. Die Reihenfolge ist keine Vorliebe mehr, sie ist eine Auszählung.

Und sie dienen ein zweites Mal, bei der Abnahme. Ist ein Bereich fertig, nimmt man seine Fragen wieder vor und prüft, ob das Referenzwerk sie beantwortet, ohne den Code zu öffnen. Die Prüfung auf halbem Weg ließ nur zwei Fragen ohne vollständige Antwort. Beide fehlten auf dieselbe Weise: eine Regel allgemein formuliert, wo die Frage die Einzelheiten erwartete — „bestimmte Vorgänge verlangen dies“ und nie, welche.

Das ist der wahrscheinlichste Mangel bei dieser Art Arbeit und der am schwersten zu sehende. Steckbriefe zu zählen hätte ihn nie gezeigt.

Ein Steckbrief pro Objekt, und Verknüpfungen dazwischen

Ein Steckbrief pro Fachobjekt, in einer Textdatei, die seinen Namen trägt. Jedes Mal, wenn ein Steckbrief ein anderes Objekt erwähnt, tut er es über eine Verknüpfung.

Diese Kleinigkeit wirkt kosmetisch. Sie ist es nicht. Die Steckbriefe und ihre Verknüpfungen bilden ein Netz, und dieses Netz lässt sich darstellen: jeder Steckbrief ein Punkt, jede Verknüpfung ein Strich. Eine Verknüpfung, die auf einen noch nicht vorhandenen Steckbrief zeigt, fällt sofort auf — sie ist das Signal, dass ein Objekt noch zu beschreiben ist.

Das Netz hört damit auf, ein hübsches Bild zu sein, und wird zur Warteschlange der Arbeit: Solange Verknüpfungen ins Leere zeigen, sind noch Steckbriefe zu schreiben.

Die Wirklichkeit auf der einen Seite, die Absicht auf der anderen

Ein Referenzwerk kann zwei sehr verschiedene Dinge beschreiben: was das Produkt tut, oder was es tun sollte. Jedes für sich ist unvollständig. Das erste lässt nie einen Mangel sichtbar werden. Das zweite verliert die Spur dessen, was wirklich existiert.

Ich behalte beides, an zwei getrennten Stellen desselben Steckbriefs. Der Hauptteil des Steckbriefs beschreibt die Wirklichkeit, so wie sie im Code steht. Ein eigener Block am Ende listet die Abweichungen auf: jede Stelle, an der diese Wirklichkeit von dem abweicht, was man wollte.

Absolute Regel: Eine Abweichung ändert nie den Hauptteil des Steckbriefs.

Die Trennung rechtfertigt sich dadurch, dass die beiden Teile nicht dieselbe Lebensdauer haben:

Der Hauptteil leitet sich aus dem Code ab: Man kann ihn wegwerfen und neu erstellen, ohne etwas zu verlieren. Die Abweichungen dagegen tragen ein Urteil — sie finden sich nirgendwo wieder, wenn sie verloren gehen. Sie zu trennen heißt, den Teil zu schützen, dessen Herstellung teuer ist.

Ein Punkt, den man oft falsch versteht: Wenn alles in Ordnung ist, schreibt man nichts. Tut das Produkt, was es soll, steht die Regel einfach im Hauptteil des Steckbriefs. Der Block der Abweichungen enthält nur die Abweichungen. Ein Steckbrief ohne Abweichung zeigt ein Objekt an, das passt, und das ist für sich schon eine Information.

Fünf Arten von Abweichung genügen, und sie sind es, die das Referenzwerk in Arbeitsmaterial verwandeln:

Der Ausgangspunkt: eine Momentaufnahme, zu einem bestimmten Zeitpunkt

Man beschreibt das Produkt so, wie es zu einem bestimmten Zeitpunkt ist. Eine Version des Codes und alles, was damit läuft: die Datenbank in dieser Version, die Oberflächen dieser Version, die Übersetzungen dieser Version. Das ist die Momentaufnahme.

Was darauf zu sehen ist, ist der Anfangszustand, ohne Geburtsdatum: Ich versuche nicht herauszufinden, wann jedes Feld entstanden ist. Die Geschichte des Produkts nachzubauen hieße, Jahre von Archiven zu durchwühlen, ohne jeden Nutzen.

Später macht man eine neue Momentaufnahme und bringt die Steckbriefe mit dem auf Stand, was sich zwischen beiden bewegt hat. Das ist der ganze Mechanismus.

Nur eines ist im Auge zu behalten, und genau da bin ich hereingefallen: Eine Quelle, die nicht von der Momentaufnahme stammt, ist keine Quelle. Darauf komme ich weiter unten zurück.

Vier Orte zum Lesen, keiner davon freiwillig

Ein und dasselbe Objekt wird an vier Orten im Produkt beschrieben, und jeder sagt, was die anderen verschweigen:

Ein Bereich des Produkts ist erst fertig, wenn alle vier gelesen wurden. Eine Regel kann sehr wohl nur an einem einzigen Ort stehen.

Die Oberflächen liest man nach dem Kern des Codes und bevor man das Thema schließt. Das ist keine Forderung nach Vollständigkeit, sondern ein Detektor für Abweichungen:

Eine Regel, die es nur in der Oberfläche gibt, ist fast immer eine Abweichung.

Entweder ist es eine echte Fachregel am falschen Ort — ein Ärgernis. Oder sie lässt sich umgehen, indem man an der Oberfläche vorbeigeht, über einen Dateiimport oder über die Schnittstelle, die das Produkt externen Entwicklern anbietet — seine API. Dann ist es ein Fehler, mit einem Sicherheitsrisiko: Was die Oberfläche verbietet, erlaubt ein anderer Weg.

Den umgekehrten Fall gibt es auch, und er wird genauso behandelt. Eine Regel, die der Kern des Codes durchsetzt, die die Oberfläche aber nicht abbildet, erzeugt eine unverständliche Fehlermeldung: Der Nutzer bekommt seine Aktion verweigert, ohne zu sehen, was er falsch gemacht hat.

Zwei Beobachtungen zu diesem Lesen der Oberflächen.

Erstens: Der Zuschnitt der Oberflächen deckt sich nicht mit dem des Codes. Für mehrere Bereiche der Oberfläche gab es auf der Serverseite keine Entsprechung. Der Abgleich geschieht deshalb Objekt für Objekt, nie Ordner für Ordner.

Zweitens ein Kniff, der in den am schlechtesten aufgeräumten Teilen des Codes Gold wert ist: Die Namen der technischen Fehlermeldungen sind oft die beste Quelle für Regeln. Eine Entwicklerin, die eine Aktion verweigert, legt einen Fehlerfall an, und sie benennt ihn. Ein Fehler namens CannotEditInvoicedOrder — „ein fakturierter Auftrag lässt sich nicht ändern“ — spricht ganz allein eine Regel aus. Man muss nur die Liste dieser Namen lesen, und dafür braucht man nicht programmieren zu können.

Nichts davon ist neu

Vielleicht ist das der nützlichste Punkt dieses Abschnitts. Ontologien zu bauen ist ein gewachsenes Fach mit eigener Literatur, und die Methode oben greift nur auf Bekanntes zurück:

• Iterativ statt Wasserfall. Die historischen Methoden reihten die Schritte der Reihe nach: spezifizieren, entwerfen, formalisieren, umsetzen. Sie wurden von Ansätzen abgelöst, die mit kleinen, neu kombinierbaren Stücken arbeiten. Diese Debatte ist seit rund fünfzehn Jahren entschieden.
• Der Rahmen über Fragen. Zuerst die Fragen aufzuschreiben, die das Referenzwerk beantworten muss, ist das Standardvorgehen; es hat sogar einen Namen, competency question. Sie im Support zu holen statt sie am Schreibtisch zu erfinden, steht nicht in den Handbüchern. Es kostet nichts und ändert, was man findet.
• In der Mitte anfangen. Man beginnt bei den zentralsten Fachobjekten, steigt dann zu den breiteren Kategorien auf und zu den Sonderfällen hinab. Die beiden anderen Wege scheitern: Von der Datenbank auszugehen heißt, die technische Struktur so abzuschreiben, wie sie ist, mit ihren Tabellen, die fachlich nichts bedeuten; von einer allgemeinen Theorie dessen auszugehen, was existiert, ergibt einen Bau, der in keinem Verhältnis zum Bedarf steht.
• Strenge im Verhältnis zur Nutzung. Man macht es sich schwer, wenn es nötig ist, nicht aus Prinzip.
• Nicht neu erfinden, was genormt ist. In den meisten Branchen gibt es Klassifikationen, die als Referenz gelten. Man muss sie anschauen — und jede Abweichung zwischen dem eigenen Modell und ihnen als Frage behandeln, die zu klären ist, nicht als Kleinigkeit.

Drei Abschlusskriterien. Dreimal falsch.

Das hier ist der Teil, für den dieser Artikel existiert.

Zuerst zwei verworfene Strategien

Zu wissen, wonach man sucht, sagt noch nicht, in welcher Reihenfolge man das Produkt durchgeht. Zwei Wege bieten sich von selbst an, und beide scheitern.

Alles lesen, in der Reihenfolge der Dateien. Ohne Priorität gibt es weder eine Reihenfolge des Eintreffens noch eine Struktur, die sich herausbildet. Die Ordnerstruktur hat nichts mit fachlicher Bedeutung zu tun, und was nur aus technischen Gründen da ist, wird auf derselben Ebene beschrieben wie die echten Fachobjekte. Man erhält eine Masse von Steckbriefen und weiß nicht, welche zählen.

Von der Datenbank ausgehen und einen Steckbrief pro Tabelle schreiben. Nützlich, aber unzureichend, und auf einer Verwechslung gebaut: Eine Tabelle ist kein Fachobjekt. Viele Tabellen dienen nur dazu, zwei andere Tabellen zu verbinden, eine technische Spur zu sichern, Anmeldetoken oder Zwischenergebnisse zu speichern. Für jemanden, der über das Produkt spricht, haben sie keinerlei Bedeutung.

Ich habe deshalb einen dritten Weg gewählt: ein Produktbereich nach dem anderen, vom Kern des Fachs zur Peripherie, gestützt auf den Zuschnitt, den der Code schon mitbringt. Eine etwas größere Software ist in Module zerlegt — Code-Bereiche, die grob den fachlichen Bereichen entsprechen: die Fakturierung, der Einkauf, die Zugriffsrechte. Diesen Zuschnitt haben Entwickler gemacht, aber er ist bereits eine teilweise Beschreibung des Fachs, gratis und durch den Gebrauch bestätigt.

Das war die richtige Entscheidung. Sie hat das Folgende nicht verhindert.

Erstes Kriterium: „Das Netz der Steckbriefe ist geschlossen“

Alle genannten Steckbriefe existieren, keine Verknüpfung zeigt mehr ins Leere. Also ist es fertig.

Das ist falsch, und der Grund ist mechanisch. Eine Menge von Steckbriefen, die nur sich selbst zitieren, schließt ihr Netz lange bevor sie das Produkt abgedeckt hat. Bei mir hat sich das Netz geschlossen, als erst eine Minderheit der Module zu einem Steckbrief geführt hatte.

Was diese Prüfung wirklich bewies: dass die Menge in sich stimmig ist. Sonst nichts. Es ist eine gute Prüfung, man sollte sie behalten — aber sie beantwortet nicht die gestellte Frage.

Die anschließende Prüfung der Abdeckung brachte zwei zentrale Fachobjekte zum Vorschein, nach denen im Netz nichts verlangt hatte.

Zweites Kriterium: „Ich habe alle meine Quellen durchgearbeitet“

Der Code der beiden Anwendungen, die Datenbank, die API, das Glossar, die Gesprächsprotokolle, die Support-Tickets. Nichts mehr zu öffnen.

Das stimmt, und es beweist nichts. Es ist eine Aussage über das, was ich geöffnet habe, nicht über das, was existiert. „Ich habe meinen ganzen Stapel gelesen“ sagt nichts über die Bibliothek: Solange das Produkt nicht aufgezählt ist, hat „alles“ keinen Nenner. Ein Modul, das nie auf meiner Liste stand, steht auch in meinem „alles“ nicht.

Drittes Kriterium: „Jeder Bereich wurde an den vier Orten gelesen“

Der Kern des Codes, die Datenbank, die Oberflächen, die Übersetzungen.

Auch wahr, und aus demselben Grund unzureichend: Es gilt nur für die Bereiche, die ich erkannt hatte. Das Kriterium misst die Tiefe, es sagt nichts über die Breite. Man kann bei einer Minderheit der Module vier Orte lesen und den ganzen Rest übersehen — und genau das ist passiert.

Die Diagnose

Nehmen wir die drei noch einmal, und das, was jedes wirklich bewies.

Alle drei sagen dasselbe: Ich habe beendet, was ich begonnen hatte. Keines sagt: Es ist nichts mehr übrig.

Man wählt ein Kriterium, das man erfüllen kann, statt eines, das die geleistete Arbeit beweist.

Das ist der Unterschied zwischen „Ich habe alles weggeräumt, was auf meinem Schreibtisch herumlag“ und „Hier ist die Liste dessen, was ich wegräumen sollte, alles ist abgehakt“. Der erste Satz stimmt, und er verpflichtet zu nichts. Der zweite setzt voraus, dass man die Liste vor dem Anfangen gemacht hat.

Das ist keine Unehrlichkeit, es ist eine Frage der Kosten.

Ein Kriterium, das man erfüllen kann, liegt schon bereit: Man schaut auf das, was man gerade getan hat, und stellt fest, dass es getan ist. Ein Kriterium, das beweist, verlangt dagegen, noch etwas herzustellen — die Liste dessen, was existiert, eine Art, sie zu zählen, eine Zahl, die jemand anders nachrechnen könnte. Das ist zusätzliche Arbeit, und sie wird genau in dem Moment verlangt, in dem man sich für fertig hält.

Daher das einzige Gegenmittel, das ich kenne: das Abschlusskriterium am Anfang wählen, nicht am Ende. Es am Ende zu suchen heißt, es unter denen zu wählen, die man ohnehin schon sicher erfüllt.

Das einzige Kriterium, das hält

Das Produkt aus mehreren unabhängigen Blickwinkeln aufzählen und für jeden messen, welcher Anteil einem Steckbrief entspricht.

Jeder Blickwinkel sieht, was die anderen nicht sehen können:

Und vor allem: Das nützliche Signal ist der Widerspruch zwischen zwei Blickwinkeln. Ein Objekt, das in einem auftaucht und in den anderen fehlt, ist entweder ein übersehenes Fachobjekt oder reine Technik. Die Frage lässt sich in einer Zeile entscheiden — aber sie wird ausdrücklich entschieden, nie im Vorbeigehen übersehen.

Die anderen Fehler

Vier, kleiner, alle teuer.

Eine Quelle lesen, die nicht auf der Momentaufnahme war. Der Datenbankexport, den ich hatte, war mehrere Monate vor der Code-Version erzeugt worden, die ich beschrieb. Ich habe ihn gelesen, als beschriebe er dasselbe Produkt. Er beschrieb ein älteres: In einem ganzen Bereich waren die Objekte im Code vorhanden, ohne jede passende Tabelle im Export, und ich habe daraus geschlossen, dass es sie nicht gab.

Die Regel ist einfacher, als ich damals dachte. Sie lautet nicht „vor dem Schluss das Datum prüfen“ — sie lautet, dass eine Quelle, die nicht von der Momentaufnahme stammt, keine Quelle ist. Man ersetzt sie durch eine aktuelle Fassung, oder man verzichtet auf sie.

Und die Feinheit, auf die es ankommt, weil ich sie zuerst übersehen hatte: Wenn zwei Teile derselben Momentaufnahme sich widersprechen — der Code auf der einen Seite, die Datenbank oder die Oberfläche auf der anderen, zum selben Zeitpunkt, in Produktion —, dann ist das kein Zeitversatz. Es ist ein Widerspruch im Produkt. Genau danach sucht man.

Eine Suche für eine Inventur halten. Ich hatte den gesamten Code in einer Suchmaschine nach Bedeutung indexiert — das Prinzip von RAG: Man stellt seine Frage in normaler Sprache, das Werkzeug liefert die Passagen, die ihr am nächsten kommen. Das ist ungeheuer wirksam, um eine Regel wiederzufinden, die mitten in einer Datei vergraben liegt und die ihr Name in keiner Weise ankündigte.

Aber eine solche Maschine antwortet immer, und sie antwortet immer mit einer Rangliste: Hier sind die zehn Passagen, die Ihrer Frage am nächsten kommen. Sie sagt nie „es gibt keine“. Eine Suche, die nichts Interessantes zurückbringt, kann also zweierlei heißen — die Sache existiert nicht, oder ich habe die Frage schlecht gestellt. Zu entscheiden ist das nicht.

Daher die Regel: erst aufzählen, dann suchen. In der anderen Richtung erhält man ein Referenzwerk aus dem, was die Maschine gerade liefern wollte.

Zwei Einzelheiten, die teuer kommen. Die Maschine hatte ihr eigenes Datum, eine Version hinter dem Code. Und man muss die Frage in der Sprache des Codes stellen: Eine französische Anfrage auf englischsprachigem Code liefert mittelmäßige Ergebnisse, selbst wenn die Antwort dort steht.

Dieselbe Regel an drei Orten aufschreiben. Unterwegs sind drei Dokumente entstanden: - die Vorlage des auszufüllenden Steckbriefs, - das Methodendokument, - die Arbeitsanweisungen, die ich dem Agenten gab.

Ein und dieselbe Regel — zum Beispiel „eine Abweichung ändert nie den Hauptteil des Steckbriefs“ — stand am Ende in allen dreien, jedes Mal mit etwas anderen Worten.

Solange man nichts ändert, stört das niemanden. An dem Tag, an dem die Regel sich ändert, korrigiert man eines, vergisst die beiden anderen, und drei Dokumente widersprechen sich, ohne dass jemand weiß, welches gilt. Eine KI weniger als alle anderen: Sie liest alle drei, ohne zu merken, dass sie auseinandergehen, und stützt ihre Analyse auf das, was sie zuerst geöffnet hat.

Jede Regel lebt jetzt an einem einzigen Ort. Die Vorlage des Steckbriefs beschreibt nur noch die Form — welche Felder, welche erlaubten Werte — und verweist für alles andere auf die Methode. Eine einzige Quelle pro Regel.

Die Ironie ist mir damals nicht aufgefallen: Ich baute ein Referenzwerk, das doppelte Definitionen abschaffen sollte, und verdoppelte dabei seine eigenen Regeln über drei Dateien.

Falsch zählen. Ich wollte wissen, welche Wörter die Kunden wirklich benutzen und wie oft. Also habe ich die Vorkommen jedes Fachbegriffs in mehreren Hundert Gesprächsprotokollen gezählt.

Erstes Ergebnis: Ein Kürzel aus zwei Buchstaben tauchte mehrere Tausend Mal auf. In Wirklichkeit gab es zwei davon. Die Suche zählte alle Stellen mit, an denen diese beiden Buchstaben innerhalb eines anderen Wortes standen. Suche „CA“ auf diese Weise, und du erntest „cadre“ (Rahmen), „cas“ (Fall), „scanner“, „application“ (Anwendung).

Man muss also ganze Wörter zählen und die Groß- und Kleinschreibung berücksichtigen, wenn der Begriff ein Kürzel ist. Ein falscher Zähler ist schlimmer als gar keiner: Er sieht aus wie ein Datenpunkt.

Den umgekehrten Fehler gibt es auch, und er ist heimtückischer. Ein Begriff, den ich im Produkt nicht vermutet hatte, stand dort sehr wohl, aber in einer ganz anderen Bedeutung, in einer technischen Ecke ohne jeden Bezug zum Fach. Eine Abwesenheit prüfen, bevor man daraus auf eine Lücke schließt.

Und eine Abweichung, die keine war

Ich hatte eine Abweichung festgehalten, die besagte, eine bestimmte Art von Verknüpfung zwischen Objekten sei im Produkt nicht richtig beschrieben. Nach der Prüfung: Sie war es doch.

Die Abweichung bleibt im Steckbrief, als abgelehnt markiert, mit dem Grund der Ablehnung. Sich zu irren gehört zur Arbeit, sofern der Irrtum eine brauchbare Spur hinterlässt — sonst macht in sechs Monaten jemand anders denselben Fehler noch einmal.

Der Agent erfasst. Der Mensch öffnet wieder.

Die Arbeit wurde von einem Agenten geleistet — einer KI, der man eine lange Aufgabe anvertraut — unter meiner Leitung. Das ist wohl der am besten übertragbare Teil dieses Erfahrungsberichts, weil er nicht nur von Ontologie handelt.

Eine Bemerkung zur Methode: Dieser Abschnitt stützt sich auf niemandes Erinnerung. Das Entscheidungsregister des Projekts ist das Protokoll meiner Eingriffe — jeder Eintrag trägt seinen Grund, also was ich korrigiert habe und warum. Das Fortschrittsprotokoll zeigt, was der Agent zwischen zwei Abwägungen produziert hat. Alles Folgende steht in diesen beiden Spuren.

Was ein Agent bemerkenswert gut kann: aufzählen, abgleichen, zählen, eine Nachverfolgung Zeile für Zeile führen und die Übersetzungen des zwölften Bereichs mit derselben Sorgfalt lesen wie die des ersten. Diese Arbeit ist massiv repetitiv, und genau das machte sie bisher unwirtschaftlich.

Was er schlecht kann: die Arbeit für beendet erklären. Die drei falschen Abschlusskriterien kamen nicht aus dem Nichts — jedes wurde als Beweis der Fertigstellung vorgeschlagen, und jedes Mal musste ich es ablehnen. Der Denkfehler ist derselbe wie bei einem müden Menschen am Projektende, nur dass der Agent die Müdigkeit nicht als Entschuldigung hat: berichten und liefern zu verwechseln.

Meine Eingriffe, wie sie sich in den Gründen der Entscheidungen lesen lassen, fallen in drei Kategorien:

• Einen Umfang erweitern, den er stillschweigend verkleinert hatte. Der Agent las den Kern des Codes und hörte dort auf. Die Regel der vier Orte, die Oberflächen eingeschlossen, kommt daher — und ausgerechnet in den Oberflächen stecken die interessantesten Abweichungen.
• Eine Struktur korrigieren, die auseinanderzugehen drohte. Dieselbe Regel an drei Orten: Er hatte sie aus dem Wunsch, es gut zu machen, abgeschrieben, und genau das durfte er nicht tun.
• Ein zu bequemes Abschlusskriterium ablehnen. Dreimal.

Was diese Abwägung möglich macht, hält in vier Vorkehrungen, und sie gelten für jede delegierte Arbeit — an eine Maschine wie an einen Menschen:

1. Ein Abschlusskriterium, das ein Dritter überprüfen kann. Nicht „ich habe alles gelesen“, sondern eine Liste und eine Quote.
2. Eine Messung, die man neu laufen lassen kann, statt einer Behauptung. Zwischen „das ist abgedeckt“ und „hier ist der Befehl, der es prüft“ liegt der ganze Unterschied zwischen einem Versprechen und einer Tatsache.
3. Eine schriftliche Nachverfolgung, in der richtigen Körnung. Eine Zeile pro Bereich und pro zu lesendem Ort, laufend aktualisiert. Sie überlebt die Unterbrechung der Arbeit, und sie verhindert, dass dasselbe zweimal gemacht wird.
4. Das Aufzählen vor dem Suchen. Zuerst das Sichere, danach und ergänzend das Wahrscheinliche.

Das Ergebnis, und sieben Wege zu prüfen, dass nichts fehlt

Was dabei herausgekommen ist, nachdem das richtige Kriterium angewendet wurde.

Mehrere Dutzend beschriebene Fachobjekte. Einige Hundert Regeln. Ebenso viele Verknüpfungen zwischen ihnen. Zahlreiche festgehaltene Abweichungen. Keine Verknüpfung mehr, die ins Leere zeigt.

Die Ausgangsfragen finden ihre Antwort, ohne dass der Code geöffnet wird.

Die Abdeckung, gemessen

Das Prinzip besteht aus drei Handgriffen. Ich liste die Objekte eines Blickwinkels — die Module, die Tabellen, die Ereignisse, die Oberflächen, die von der API bereitgestellten Ressourcen. Ich schaue für jedes nach, ob es einem Steckbrief entspricht. Ich zähle.

Die sieben gewählten Blickwinkel: die Module der Anwendung A, die Tabellen der Datenbank, die von der Software ausgelösten Ereignisse, die Oberflächen der Anwendung A, die Module und die Objekte der Anwendung B, die von der API bereitgestellten Ressourcen.

Die erreichten Quoten liegen je nach Blickwinkel zwischen 70 und 95 Prozent.

Die Messung lässt sich mit einem kleinen Programm wiederholen. Das ist der entscheidende Punkt: Es ist keine Behauptung, es ist eine Prüfung, die jemand anders neu laufen lassen kann.

Und es ist eine schwache Messung, was im selben Atemzug gesagt werden muss. Der Abgleich läuft über die Namen: Eine Tabelle sales_order wird als der Steckbrief „Sales Order“ erkannt, Großschreibung, Bindestriche und Pluralformen beiseitegelassen.

Das klappt ungefähr in der Hälfte der Fälle. Beim Rest ähneln die Namen einander überhaupt nicht — eine Tabelle kann so_header heißen, während der Steckbrief „Sales Order“ heißt. Ich habe deshalb nebenher eine Liste von Entsprechungen geführt, Zeile für Zeile aufgeschrieben, sobald ich darüber stolperte: diese Tabelle da ist dieses Objekt da.

Diese Liste ist ein Urteil, keine Regel. Vergesse ich eine Zeile, erscheint das Objekt als nicht abgedeckt, obwohl es das ist. Füge ich eine zweifelhafte hinzu — „na komm, diese Tabelle muss doch zu diesem Steckbrief passen“ —, blase ich meine eigene Quote auf. Und selbst wenn die Namen übereinstimmen, kann das Zufall sein: zwei verschiedene Dinge unter demselben Wort.

Die Messung beweist also nichts. Sie zeigt, wo man hinschauen muss.

Warum ich nicht auf 100 Prozent ziele

Das ist der naheliegende Einwand: Wenn ich den Anteil der Module kenne, die keinen Steckbrief haben, weiß ich auch, welche es sind — man muss sie nur beschreiben.

Nur ist das leere Kästchen keine Aufgabe, sondern eine Frage. Jedes Objekt ohne Steckbrief ist entweder ein Fachobjekt, das ich übersehen habe, oder reine Technik ohne jede fachliche Bedeutung: eine technische Warteschlange, ein Dienst, der Bilder skaliert, eine Tabelle mit Anmeldetoken, eine Navigationsoberfläche. 100 Prozent zu erreichen hieße, einen Steckbrief „Warteschlange“ und einen Steckbrief „Token“ anzulegen — also das Referenzwerk zu verschmutzen, damit eine Zahl steigt.

Der Zähler hat deshalb drei Zustände, nicht zwei:

Was 100 Prozent erreichen muss, ist die dritte Zeile auf null — nichts mehr, was nicht geprüft wäre. Der angezeigte Prozentsatz dagegen steigt nicht auf 100 und muss es auch nicht.

Hier wurde der Rest von Hand durchgesehen: Technik, interne Mechanismen, Oberflächen ohne eigenes Fachobjekt. Kein Fachobjekt hatte sich darin versteckt. Aber das ist eine Prüfung von Hand, bei jeder Weiterentwicklung zu wiederholen — und das ist die Schwäche, die bleibt.

Die Zahl dient also etwas anderem als der Messung des Fortschritts. Sie dient dazu, die Blickwinkel miteinander zu vergleichen. Die niedrigste der sieben Quoten, bei den Objekten der Anwendung B, gegen die höchste, bei den Ereignissen: Der Abstand heißt nicht „da bleibt noch all diese Arbeit“, er heißt „die Anwendung B verarbeitet Dinge, die der Rest des Produkts nicht kennt, schaut mal dort nach“. Dieser Widerspruch hat die vier folgenden Funde zutage gefördert.

Was die Blickwinkel eingebracht haben

Vier Objekte, die auf keinem anderen Weg gefunden worden wären:

• Über die Tabellen der Datenbank. Ein Objekt, das das Produkt anzeigt, das aber zu keinem Bereich des Codes gehört — im fiktiven ERP wäre das die kommende Fälligkeit einer Rechnung: Der Kunde sieht sie in seinem Fälligkeitsplan, aber sie existiert erst wirklich in dem Moment, in dem die Rechnung erstellt wird. Diese Zweideutigkeit erklärt eine ganze Familie von Kundenreklamationen.
• Über die Ereignisse. Eine ganze Teilmenge eines Bereichs, den man für abgedeckt hielt, enthüllt durch die Ereignisse, die er auslöste und die niemand irgendetwas zugeordnet hatte.
• Über die API. Einige Objekte, über mehrere Module verteilt — also unsichtbar, solange man Bereich für Bereich vorgeht, und dennoch vertraglich nach außen bereitgestellt.
• Über die Anwendung B. Zwei Objekte, die sie verarbeitet und die die Anwendung A nicht kennt.

Die Probleme, die überall wiederkehren

Hier sind die Funde, auf das fiktive ERP übertragen. Es sind Arten von Problem, keine Einzelfälle — und ich würde wetten, dass keines davon in deinem Produkt fehlt.

Ein Zustand, überall neu berechnet, nirgends definiert. Der Status eines Auftrags, aus ein paar Daten und dem Zustand seiner Positionen abgeleitet, in jeder Oberfläche neu berechnet, ohne zentrale Regel. Irgendwann sagen zwei Oberflächen nicht mehr dasselbe, und niemand weiß, welche recht hat.

Ein Objekt, das der Nutzer sieht und nicht wiederfinden kann. Die Rechnungsfälligkeit, von der ich sprach: im Fälligkeitsplan angezeigt, in den Suchergebnissen nicht vorhanden, weil sie noch nicht als Beleg existiert. Der Nutzer aber hat sie auf dem Bildschirm gesehen — er sucht sie also, findet sie nicht und öffnet ein Ticket. Der Support antwortet seit Jahren von Fall zu Fall, ohne dass die Ursache irgendwo aufgeschrieben wäre.

Ein Wert, der keiner ist. Der Saldo eines Kunden ist keine Zahl, die irgendwo abgelegt ist: Er ist das Ergebnis einer Berechnung über alle seine Rechnungen, Zahlungen, Gutschriften und Ausgleichsbuchungen. Solange das unausgesprochen bleibt, greift jede neue Funktion, die „den Saldo liest“, auf das falsche Objekt zu und liefert eine leicht abweichende Zahl, je nachdem, an welche Bewegungen sie gedacht hat. Drei Oberflächen, drei Salden.

Eine Regel, die nur auf einer Seite greift. Die Rabattobergrenze wird im Eingabeformular geprüft und sonst nirgends — also über einen Dateiimport oder über die API umgehbar. Das ist der Detektor für Abweichungen, von dem ich oben sprach, und seine Ausbeute ist bemerkenswert.

Eine Berechtigung, aus sechs Quellen berechnet, ohne einen Ort, der sie zusammenführt. Die Rolle der Person, der abgeschlossene Tarif, die aktivierten Optionen, die Einschränkung der Testphase, der Umfang ihrer Tochtergesellschaft, eine Ausnahmeliste. Nirgends im Produkt steht „so berechnet sich eine Berechtigung“. Jede Weiterentwicklung entdeckt es auf eigene Kosten neu.

Ein und dasselbe Objekt, auf jeder Ebene anders benannt. „Auftrag“ auf der Oberfläche, ein Wort im Code, ein anderes in der zweiten Anwendung, „Geschäft“ in der Praxis. Vier Vokabulare für das zentralste Objekt des Produkts.

Ein Wort, das die Kunden ständig benutzen und das das Produkt nicht kennt. In diesem Korpus von Gesprächen kehrt ein Begriff mehrere Dutzend Mal wieder, ein anderer etwas seltener. Keiner von beiden existiert im Produkt, unter keinem Namen. Das sind keine Vokabelabweichungen, das sind Entwurfslücken — und sie treten erst hervor, wenn man vergleicht, was die Kunden sagen, mit dem, was das Produkt tut.

Die Nebenprodukte

Keines war das Ziel. Alle sind aus der Arbeit abgefallen.

Bug-Kandidaten. Das Produkt widerspricht einer irgendwo aufgeschriebenen Erwartung. Jeder kommt mit seinem Beleg und seiner Folge, nicht mit einer Ahnung.

Ein Kundenvokabular, mit Häufigkeiten. Zählt man die Wörter über einen umfangreichen Korpus von Gesprächsprotokollen und Support-Tickets, erhält man für jedes Objekt des Produkts die tatsächlich benutzten Begriffe und ihr Gewicht. Wer mit dem Kunden spricht, weiß dann, welches Wort er verwenden soll. Ein Begriff kehrt mehr als hundert Mal wieder und bezeichnet einen Umfang, den das Produkt anders nennt; ein anderer fast ebenso oft das zentrale Objekt.

Und diese beiden Korpora sagen nicht dasselbe. Die Gespräche sagen, was die Kunden bauen wollen. Die Tickets sagen, was kaputtgeht. Ein und dasselbe Wort kann im einen dominieren und im anderen fehlen. Sie zusammen zu zählen heißt, falsch zu priorisieren.

Eine Bestandsaufnahme der Übersetzungen. Das mehrsprachige Glossar deckt nur eine Minderheit der beschriebenen Objekte ab. Von den Fehlenden werden einige dem Nutzer sehr wohl in allen Sprachen angezeigt: Für sie existiert keine verbindliche Übersetzung. Und von allen Sprachen des Glossars ist nur ein kleiner Teil gegengelesen worden.

Was es kostet, und was die Methode immer noch nicht sagt

Die Kosten

Weniger als sechs Stunden. So lange hat das Ganze gedauert: die Steckbriefe, die Regeln, die Messungen der Abdeckung. Eine Sitzung, von Anfang bis Ende.

Vor dem Beginn hatte ich einige Dutzend Stunden geschätzt, Bereich für Bereich verteilbar. Ich habe mich um eine Größenordnung geirrt — und dieser Schätzfehler ist vielleicht der wahre Grund, warum diese Arbeit vorher niemand gemacht hat: Man hält sie für unerreichbar und fängt deshalb gar nicht erst an.

Drei Vorbehalte zu dieser Zahl, damit sie ehrlich bleibt. Es ist eine Messung an einem Produkt, einmal, kein Durchschnitt. Die Quellen waren bereits zusammengetragen und lokal indexiert; die Zeit für die Einrichtung steckt nicht darin. Und sie sagt genauso viel über die Werkzeuge wie über die Methode: Dieselbe Arbeit von Hand hätte Wochen gedauert, und genau deshalb war sie nie gemacht worden.

Die Bedingung für die Rentabilität ist dagegen klar: einen Bereich zu Ende bringen, bevor man einen anderen aufmacht. Ein Referenzwerk, das für ein Gebiet vollständig ist, nützt sofort allen Fachbereichen dieses Gebiets. Ein halb fertiges Referenzwerk über fünf Gebiete nützt niemandem.

Die Pflege

Das ist die Frage, die immer als zweite kommt, und sie ist berechtigt: Ein Referenzwerk, von dem niemand sagt, wie es lebendig bleibt, interessiert niemanden.

Die Referenzversion dient als Bezugspunkt: Sie liefert mit einem einzigen Befehl die genaue Liste dessen, was sich im Produkt seit der letzten Aktualisierung bewegt hat — also die Liste dessen, was noch festzuhalten ist.

Jeder Steckbrief führt ein Protokoll, in das man Einträge hinzufügt, ohne je die vorherigen zu korrigieren. Ein Eintrag, der eine Code-Version nennt, zeigt an, dass das Produkt sich geändert hat. Ein Eintrag ohne Code-Version zeigt etwas anderes an: Dann hat sich unser Verständnis geändert, nicht das Produkt. Der Unterschied wirkt nebensächlich; er ist es, der sechs Monate später erkennen lässt, ob wir einen Steckbrief korrigiert haben oder ob die Software sich weiterentwickelt hat.

Zwei Bewegungen verdienen eine Erwähnung, weil kein Werkzeug sie erzählt: die Verschmelzung zweier Objekte, die man für verschieden hielt, und die Teilung eines Objekts, das zwei verbarg. Das sind die häufigsten Bewegungen, wenn ein Referenzwerk reift.

Und wenn ein Objekt von Grund auf neu gedacht wird, ändert man seinen Steckbrief nicht: Man legt einen neuen an, und der alte bleibt. Er beschreibt, was das Produkt gewesen ist, und er bleibt nötig, um Daten und Vorgänge von vor der Änderung zu deuten.

Was ich bewusst nicht gemacht habe

• Kein Nachbau der vergangenen Geschichte des Produkts.
• Kein Einbezug der Datenexporte: Sie sind abgeleitete Sichten auf das Produkt, nicht das Produkt selbst.
• Kein gelehrtes Werkzeug, solange keine Nutzung danach verlangt.

Was die Methode noch nicht sagt

• Wie weit die Strenge des Formats zu treiben ist. Das hängt von der Nutzung ab, und die Nutzung hat nicht begonnen.
• Wie eine alte Datei dem richtigen Zustand eines Objekts zuzuordnen ist, wenn dieses Objekt zwischenzeitlich neu gedacht wurde.
• Wer einen Steckbrief gegenliest, und nach welchen Kriterien, bevor er ins Referenzwerk aufgenommen wird.
• In welchem Takt der Ausgangspunkt zu aktualisieren ist, um das Bewegte nachzuholen.

Ein Methodendokument, das sich für vollständig ausgibt, lügt. Dieses trägt einen Abschnitt „was es noch nicht sagt“, und der schrumpft, während die Fragen entschieden werden.

Fazit: Das Abschlusskriterium ist die eigentliche Lieferung

Wenn ich aus diesem Projekt nur eines behalten dürfte, wäre es der Satz, der die drei Fehlstarts erklärt:

Man wählt ein Kriterium, das man erfüllen kann, statt eines, das die geleistete Arbeit beweist.

Er betrifft nicht nur Ontologien. Er gilt für ein Audit, eine Migration, eine Sicherheitsprüfung, den Abbau technischer Schulden. Jedes Mal, wenn eine Arbeit mit „ich habe alles angeschaut“ endet, lautet die Frage: Alles, das heißt? Hast du die Liste?

Zwei Prüfungen, nie nur eine. Ob die Menge in sich stimmt, prüft man, indem man die Steckbriefe untereinander betrachtet. Ob sie vollständig ist, prüft man, indem man das Produkt aufzählt. Beides zu verwechseln hat hier einen erheblichen Teil des Produkts gekostet.

Bleibt das Interessanteste, und das ist nicht getan: die Abweichungen. Sie warten alle darauf, aufgearbeitet zu werden — zuerst die Bug-Kandidaten, dann die, die eine Kundenanfrage bereits stützt, dann die Lücken, dann die Entwurfsschuld. Das ist keine Beschreibung mehr, das ist Produktentscheidung.

Das ist ein anderer Artikel, und er lässt sich erst danach schreiben.

Anhang A — Wie ein Steckbrief aussieht

Dieser Anhang ist der technischste Teil des Artikels; man kann vorher aufhören, ohne etwas vom Gedankengang zu verlieren.

Der Steckbrief unten ist auf das fiktive ERP übertragen. Er beschreibt die Form — die Regeln, die ihn beherrschen, leben im Methodendokument, an einem einzigen Ort.

Was ein Steckbrief enthält

Der Steckbrief selbst

Die Datei trägt den Namen des Objekts — das ist es, was die Verknüpfungen zwischen den Steckbriefen von selbst auflösen lässt.

---
konzept: Sales Order
definition: Lieferzusage gegenüber einem Kunden, verfolgt von ihrer Erfassung bis zu ihrer Fakturierung.
elternobjekt:
kindobjekte: ["[[Rush Order]]", "[[Standing Order]]"]
attribute:
  - name: status
    typ: enum
    werte: [draft, confirmed, shipped, invoiced]
relationen:
  - verb: placed-by
    ziel: "[[Customer]]"
    kardinalitaet: 1..1
  - verb: contains
    ziel: "[[Order Line]]"
    kardinalitaet: 1..n
axiome:
  - Ein fakturierter Auftrag kann keine Position mehr aufnehmen
lexikon:
  de: [Auftrag, Kundenauftrag]
  en: [sales order]
  es: [pedido]
  synonyme_praxis: [Geschäft, Vorgang]
  veraltet: [Kundenbestellschein]
quellen:
  - erp.sql:Tabelle `sales_order`
  - de.json:order.status.draft
abweichungen:
  - id: E1
    art: Lücke
    bereich: relationen
    erwartet: eine Verknüpfung zu "[[Attachment]]", wie sie "[[Customer]]" hat
    folge: ein unterschriebener Auftragsschein lässt sich nicht anhängen
    status: bestaetigt
    datum: 2026-08-10
historie:
  - datum: 2026-08-10
    aktion: anlage
    grund: erste Beschreibung, auf der Referenzversion
---

# Sales Order

Lieferzusage gegenüber einem Kunden, verfolgt von ihrer Erfassung bis zu ihrer Fakturierung.

## Verknüpfungen

- *placed-by* → [[Customer]] (genau einer)
- *contains* → [[Order Line]] (mindestens eine)
- Sonderfälle → [[Rush Order]], [[Standing Order]]

## Historie

| Datum | Was passiert ist | Code-Version | Grund |
|---|---|---|---|
| 2026-08-10 | Anlage | — | erste Beschreibung |

Nur eines steht zweimal da: die Verknüpfungen. Einmal im Kopfbereich, damit Werkzeuge sie lesen können; einmal im Hauptteil, damit sie in der Netzansicht erscheinen. Alles andere existiert nur an einem einzigen Ort.

Drei Qualitätskriterien, jedem Steckbrief entgegenzuhalten: Die Definition hält in einem Satz und dreht sich nicht im Kreis; jede Verknüpfung ist von einem präzisen Verb benannt, nie von „ist verknüpft mit“; das Vokabular ist mehrsprachig und trägt die Wörter, die die Kunden benutzen.

Anhang B — Das Raster der Abweichungen

Was man zu jeder Abweichung festhält:

Die fünf Arten:

Was passiert, wenn die Abweichung verschwindet. Man markiert sie als gelöst, und sie bleibt im Steckbrief. Der Hauptteil des Steckbriefs wird auf die neue Wirklichkeit gebracht, und eine Zeile kommt ins Protokoll. Beide antworten einander: Die Abweichungen tragen die Absicht, das Protokoll trägt die Bewegung.

Eine Leitplanke. Eine Abweichung beschreibt eine strukturelle Divergenz, keinen Vorfall. Eine Zeile, ein Link zum Ticket. Die Bildschirmfotos, die Schritte zum Nachstellen und die Einzelheiten bleiben im Ticketsystem. Ein Steckbrief ist kein Bug-Tracker.

Anhang C — Die Blickwinkel zum Aufzählen

Alle durchzugehen und paarweise gegeneinanderzustellen.

Drei Regeln für den Gebrauch:

1. Das Signal ist der Widerspruch zwischen zwei Blickwinkeln, nicht die Quote eines einzelnen Blickwinkels.
2. Jedes nicht zugeordnete Objekt wird ausdrücklich entschieden — Fachobjekt oder reine Technik. Nie durch Auslassung.
3. Zwei Kundenkorpora, getrennt gezählt: Die Gespräche sagen, was die Kunden bauen wollen, die Tickets, was kaputtgeht. Beide Häufigkeiten ins Vokabular aufnehmen — die eine lenkt die Roadmap, die andere die Dokumentation und die Schulung.

Wo die Regeln stecken, nach abnehmender Ausbeute:

1. Die Namen der technischen Fehlermeldungen. In den am schlechtesten aufgeräumten Teilen des Codes sind sie oft die einzige Quelle — und man liest sie, ohne programmieren zu können.
2. Die Prüfungen zu Beginn eines Vorgangs, bevor irgendetwas geändert wird.
3. Die Bedingungen der Datenbank — was eindeutig sein muss, was nicht leer bleiben darf. Sie widersprechen manchmal dem Fach, und diese Abweichung ist ein Fehler.
4. Die Eingabeprüfungen in den Oberflächen — der am häufigsten vergessene Teil, und der, der die interessantesten Abweichungen liefert.

Ein Objekt, das ohne jede Regel beschrieben ist, zeigt eine oberflächliche Beschreibung an, nie ein Fach ohne Regeln.