Website und Produkt sind jetzt zwei Dinge

Diesen Text zu veröffentlichen, hätte vor einer Woche bedeutet: eine React-Komponente schreiben, einen Eintrag in einer Routentabelle ergänzen, make build laufen lassen und die Control Plane neu starten. Ein Blogbeitrag wäre ein Deploy der Plattform gewesen.

Das lag daran, dass die Website Teil des Produkts war. Covey ist ein einzelnes Go-Binary, und die Weboberfläche wird per //go:embed hineingebacken — die angemeldete Oberfläche ebenso wie die Startseite, die Produktseiten und die Dokumentation. Das ist für die Oberfläche genau richtig: Sie gehört zur Anwendung, sie wird mit ihr versioniert, und eine Installation soll nichts nachladen müssen.

Für die Marketing-Seiten war es falsch, und zwar aus zwei Richtungen.

Wer Covey selbst betreibt, bekam unsere Werbung mit

Covey ist quelloffen. Wer es von GitHub installiert, bekommt ein Binary — und darin lagen bisher unsere Startseite, unsere Produktseiten und demnächst dieser Blog. Auf einer Instanz im eigenen Rechenzentrum ist das nicht bloß überflüssig, es ist verkehrt: Unter / gehört dort eine Anmeldung hin, keine Anzeige für ein Produkt, das man gerade installiert hat.

Der zweite Punkt ist der praktischere. Eine Website, die Inhalte bekommen soll — Beiträge, Notizen, Fallbeispiele —, ändert sich häufiger als eine Plattform. Beides an denselben Auslieferungszeitpunkt zu binden heißt, das Häufige am Seltenen auszurichten.

Was jetzt wo liegt

Der Schnitt läuft entlang der Frage, was das Binary eines fremden Installierers ausliefern muss:

• Im Produkt bleiben Anmeldung und Registrierungsformular. Sie sprechen mit der API, sie gehören zur Anwendung.
• Auf der Website stehen Startseite, Funktionsübersicht, Integrationen, Produktseiten, Dokumentation und dieser Blog.

Die Oberfläche zieht auf app.covey.work, die Website behält covey.work. Andersherum hätte jede Adresse, die heute in einer Suchmaschine steht, ihre Position verloren.

Die Dokumentation ist der interessante Fall

Sie hätte mit umziehen können — sie wird vor der Installation gelesen und muss auffindbar sein. Genau das haben wir nicht gemacht.

Die Doku lag nämlich zweimal da: achtzehn Betriebsanleitungen als Markdown im öffentlichen Repository, und dreizehn erklärende Seiten als eine 124 KB große TypeScript-Datei neben der Website. Ausgeliefert wurde die zweite. Niemand schickt einen Pull Request gegen ein TypeScript-Literal, und man sah es den beiden Beständen an: Die Betriebsanleitungen waren aktuell, die Website-Seiten nicht.

Also liegt die Dokumentation jetzt genau einmal, als Markdown, im öffentlichen Covey-Repository — englisch als Quelle, deutsch unter demselben Pfad daneben. Die Website holt sie sich beim Bauen. Die Abhängigkeit läuft in eine Richtung: Die Website kennt das Produkt-Repository, das Produkt-Repository kennt die Website nicht. Wer einen Fehler in der Doku findet, korrigiert ihn dort, wo auch der Code liegt.

Was wir beim Aufräumen gefunden haben

Zwei Sachen, die schon länger falsch dastanden:

Eine Betriebsanleitung nannte eine Umgebungsvariable, die es nicht gibt — der Name hatte sich bei einer Umbenennung geändert, und der Satz daneben behauptete zusätzlich, sie sei "kein Schalter, den Sie brauchen". Sie ist einer: Sie entscheidet, ob überhaupt eine Sandbox auf der Maschine der Control Plane laufen darf.

Und die Website-Dokumentation erwähnte den Plugin-Katalog kein einziges Mal, obwohl seit Version 0.6.0 drei Zielsysteme — Zammad, Kubernetes und die Schwachstellen-Datenbank — nur noch von dort installiert werden. Wer die Doku auf der Website las und Zammad anbinden wollte, fand den entscheidenden Schritt nicht. Er stand in der anderen Fassung.

Beides ist behoben. Beides wäre ohne den Umzug wahrscheinlich noch eine Weile stehen geblieben — was ein ganz guter Beleg für den Punkt oben ist: Eine Doku, die niemand ändern kann, ändert niemand.