Schnittstellen dokumentieren, bevor sie brechen

Jede Integration funktioniert am Tag der Abnahme. Interessant wird sie zwei Jahre später, wenn sie ausfällt — und die Person, die sie gebaut hat, nicht mehr im Haus ist.

Dann entscheidet sich, ob es eine Dokumentation gab oder eine Beschreibung. Der Unterschied ist nicht der Umfang, sondern die Frage, die sie beantwortet.

Eine Schnittstelle ist dokumentiert, wenn jemand ohne Vorwissen den Fehlerfall nachstellen kann. Alles andere beschreibt den Normalfall — und der braucht keine Dokumentation.

Was hineingehört

Zweck in einem Satz. „Überträgt bezahlte Bestellungen aus dem Shop in die Warenwirtschaft." Klingt trivial, fehlt erstaunlich oft — und ist die einzige Zeile, die jemand liest, der nur wissen will, ob diese Strecke sein Problem betrifft.

Auslöser und Richtung. Wer ruft wen? Zeitgesteuert oder ereignisbasiert? In welchem Takt? Diese Angabe entscheidet darüber, ob „seit gestern kommt nichts" ein Ausfall ist oder normal.

Felder und ihre Bedeutung. Nicht nur die Liste, sondern die Zuordnung: Was wird woraus, welche Umrechnung passiert, welches Feld ist Pflicht, welches darf leer sein — und was bedeutet leer.

Fehlerfälle. Was passiert bei Zeitüberschreitung, bei ungültigen Daten, bei doppelter Lieferung? Und vor allem: Was passiert danach — Wiederholung, Warteschlange, Meldung?

Was regelmäßig fehlt

Diese vier Angaben fehlen in fast jeder Dokumentation, die wir übernehmen — und sie sind genau die, nach denen im Störfall gesucht wird:

Wer ist Eigentümer? Nicht wer es gebaut hat, sondern wer heute entscheidet, ob eine Änderung gemacht wird. Eine Schnittstelle ohne Eigentümer wird bei jedem Anlass neu diskutiert.

Wo liegen die Zugangsdaten? Nicht die Daten selbst — der Ort und der Weg, sie zu erneuern. Welche Endpunkte überhaupt einen Zugang verlangen und welche offen sind, steht in Welche Endpunkte Shopware ab Werk schützt. Ein abgelaufener Zugang ist eine der häufigsten Ursachen für stillstehende Ketten, und die Suche danach kostet regelmäßig mehr Zeit als die Reparatur.

Was passiert bei Ausfall? Läuft der Shop weiter? Stauen sich Bestellungen? Gehen sie verloren? Diese drei Fälle sind sehr verschieden, und die Antwort muss vorher feststehen — nicht im Moment des Ausfalls herausgefunden werden.

Wer wird benachrichtigt? Eine Meldung an ein Postfach, das niemand liest, ist keine Meldung.

Die Probe

Geben Sie die Dokumentation jemandem, der das System nicht kennt, und lassen Sie ihn eine Aufgabe erledigen:

„Die Übertragung steht seit gestern. Finde heraus, woran es liegt, und sage mir, ob Daten verloren sind."

Wenn eine dieser fünf Antworten ausbleibt, fehlt genau dort ein Absatz. Das ist die ganze Methode — sie dauert zwanzig Minuten und ersetzt jede Diskussion über Dokumentationsvorlagen.

Was die Dokumentation über den Betrieb verrät

Es gibt eine Abkürzung, um den Zustand einer Integrationslandschaft einzuschätzen, ohne eine Zeile Code zu lesen: Zählen Sie, für wie viele Strecken es eine Seite gibt.

Drei Muster, die wir dabei regelmäßig finden:

Keine Dokumentation, aber ein Mensch, der alles weiß. Funktioniert tadellos, bis dieser Mensch Urlaub hat. Das ist kein Vorwurf an die Person — es ist ein Risiko, das niemand bewusst eingegangen ist.

Dokumentation vom Tag der Abnahme. Sie beschreibt einen Stand, den es seit drei Änderungen nicht mehr gibt. Gefährlicher als keine, weil ihr jemand glaubt.

Dokumentation im Repository neben dem Code. Sie wird mit geändert, weil sie in derselben Änderung liegt. Das ist der einzige Mechanismus, der zuverlässig funktioniert — nicht weil er besser gemeint ist, sondern weil er den Aufwand an die Stelle legt, an der ohnehin gearbeitet wird.

Eine Dokumentation, die nicht im selben Vorgang geändert wird wie der Code, veraltet. Das ist keine Disziplinfrage, sondern eine Frage des Ortes.

Die eine Zeile, die am meisten spart

Wenn Sie nur eine Angabe ergänzen können, dann diese: wann der Zugang abläuft. Nicht wo er liegt, nicht wie er heißt — wann er ungültig wird.

Diese Zeile im Kalender verhindert die häufigste Ausfallursache überhaupt, und sie kostet eine Minute je Strecke.

Wo die Dokumentation liegen sollte

Nicht in der Anwendung, die ausfällt. Das klingt selbstverständlich und wird regelmäßig übersehen: Eine Beschreibung, die im Wiki des Systems steht, das gerade nicht erreichbar ist, hilft nicht.

Der Umfang, der sich bewährt hat

Eine Seite je Strecke. Nicht mehr — eine Dokumentation, die dreißig Seiten hat, wird nicht gelesen und nicht gepflegt.

Was auf diese eine Seite gehört:

Punkt 5 mit dem Ablaufdatum ist der, der am häufigsten fehlt und am zuverlässigsten zuschlägt.

Warum sich das rechnet

Eine Schnittstellendokumentation kostet zwei bis vier Stunden je Strecke. Der erste Störfall ohne sie kostet einen halben Tag Suche — und einen zweiten für die Frage, ob Daten verloren sind.

Sie ist außerdem die einzige Absicherung gegen den Fall, dass der Dienstleister wechselt. Was beim Bau einer Integration ohnehin geklärt werden muss, steht in Systeme verbinden, die nicht miteinander sprechen; warum jede Strecke einen Meldeweg braucht und keinen Protokolleintrag, in Was Shopware im Hintergrund erledigt.

Wenn Sie Strecken betreiben, die niemand mehr vollständig kennt: Wir machen die Probe oben mit Ihrer vorhandenen Dokumentation und sagen, welche Absätze fehlen. Das ist ein Termin und deutlich günstiger als der erste Störfall. Mehr dazu unter App- und Plugin-Entwicklung.