Dokumentation, die sich selbst veröffentlicht, sobald ich zustimme

Das Problem mit der Dokumentation im Homelab ist nicht das Schreiben selbst. Es ist, dass das Schreiben im Moment, in dem du den Kontext hast, nie lohnenswert ist – und wenn es dann lohnenswert wäre, hast du den Kontext nicht mehr.

Deshalb arbeitet die Pipeline rückwärts vom Artefakt her. Das System erkennt eine Lücke – einen Service ohne Seite, ein Backup ohne dokumentierte Wiederherstellung, ein Monitoring, das ins Leere zeigt – erstellt einen Entwurf für die Seite und öffnet einen Pull Request. Dann stoppt es.

Die Kette

Lücke erkennen        -> ein Vorschlags-Datensatz, in einem Runtime-Outbox, git-ignoriert
vorbereiten           -> ein Branch und ein Entwurf-Pull-Request, der nie gemerged wird
ich reviewe und merge -> die Seite landet auf main
publish-on-merge      -> die gemergte Seite erscheint im Wiki

Vier Schritte, und ich bin bei Schritt drei. Das Tool für Schritt zwei hat überhaupt keinen Merge-Aufruf – weder deaktiviert noch markiert. Die Fähigkeit fehlt komplett, was eine stärkere Garantie ist als ein ausgeschalteter Schalter.

Veröffentlicht wird nur von main gelesen

Der Publisher weigert sich, von irgendetwas anderem als dem Default-Branch zu laufen. Das klingt erstmal nach Overkill, bis du dir überlegst, wofür ein Wiki da ist: Es ist der Text, den Leute statt des Repos lesen. Eine Wiki-Seite, die von einem ungemergten Branch veröffentlicht wird, ist eine Behauptung über das System, die nie geprüft wurde – und sitzt genau da, wo Leute hingehen, wenn sie etwas vertrauen.

Das Opt-in ist pro Dokument – eine Seite trägt ein Flag, das sagt, sie darf nach Merge veröffentlicht werden – und die Republizierung wird per Content-Hash dedupliziert, sodass ein Merge, der die Seite nicht verändert hat, gar keinen Wiki-Schreibvorgang auslöst.

Drei Dinge, die mich die API des Wikis auf die harte Tour gelehrt hat

Content kommt nur über den Import-Endpunkt an. Eine Seite zu erstellen oder zu aktualisieren akzeptiert zwar einen Body, ignoriert ihn aber stillschweigend. Ein Republizieren ist also wirklich löschen, dann reimportieren, was bedeutet, dass der „Update“-Pfad in meinem Publisher eine destruktive Operation mit freundlichem Namen ist.

Und das Löschen ist ein Hard Delete. Kein Papierkorb, kein Soft-Flag. Das erste Mal, als ich das gelernt habe, war es bei einer Seite, die ich haben wollte.

Existenzprüfungen brauchen einen Pfad, keinen Titel. Meine erste Duplikatsprüfung fragte „existiert eine Seite mit diesem Titel“. Einige meiner Seiten heißen legitimerweise „Backup and Restore“ – je eine pro Service, darunter verschachtelt. Die Prüfung kollidierte sie, und der Publisher kam zum Schluss, dass er Markdown nicht sicher aktualisieren kann. Der Bug-Report sagte „Seite existiert bereits“; der eigentliche Fehler war, dass ich einen Blattnamen mit einer Identität verwechselt hatte.

Der letzte Punkt ist ein spezieller Fall eines Fehlers, den ich inzwischen in vier verschiedenen Subsystemen gemacht habe: Ein Name ist keine Identität. Zwei Hosts können beide einen Container namens redis laufen haben. Zwei Services können beide eine Seite namens Backup and Restore haben. Jede Prüfung, die einen Namen ohne Scope auflöst, wird irgendwann zwei Dinge zusammenführen, die nie dieselben waren.

Warum ich den Merge nicht automatisiert habe

Weil der Wert dieses Systems darin liegt, dass es bemerkt, und Bemerken ist billig zu verifizieren, während Veröffentlichen teuer und Zurücknehmen aufwendig ist. Eine generierte Seite zu reviewen dauert mich unter einer Minute – der Diff ist eine neue Datei und die Quellen sind inline. Etwas Falsches aus einem Wiki zu entfernen, das Leute schon gelesen haben, dauert deutlich länger, und es gibt keinen Befehl für den Teil, in dem sie es schon gelesen haben.