Wer Self-Hosting anbietet, schreibt Dokumentation — oder bekommt Tickets

Yurna war von Anfang an offen einsehbar, und irgendwann kam die logische Frage: Kann man den auch selbst betreiben? Meine Antwort war ein reflexhaftes Ja. Klar, ist ja alles da.

Die nächsten Monate haben mir beigebracht, dass „der Code ist verfügbar" und „man kann es selbst betreiben" zwei sehr verschiedene Aussagen sind.

Was in fremden Umgebungen alles anders ist

Meine Anleitung ging von meiner Welt aus: Linux, Node in einer bestimmten Version, ein Paketmanager, eine Datenbank, ein Reverse Proxy. Was tatsächlich ankam:

• Windows, mit Pfadtrennzeichen, die in Skripten stolpern.
• Eine Node-Version, die zwei Hauptversionen älter war.
• Ein anderer Paketmanager, mit dem die Abhängigkeitsauflösung anders ausfällt.
• Ein Hoster, der keine dauerhaften Prozesse erlaubt.
• Eine Datenbank auf einem anderen Rechner, mit Verbindungsproblemen, die nichts mit meinem Code zu tun hatten.
• Kein Reverse Proxy, dafür die Frage, warum die Anmeldung nicht funktioniert.

Jeder dieser Fälle wurde ein Ticket. Nicht, weil die Leute unfähig waren, sondern weil meine Anleitung Wissen voraussetzte, das ich hatte und sie nicht — und zwar unausgesprochen.

Die drei Sorten Lücken in Anleitungen

Die vergessene Voraussetzung. Ich hatte „Node 18+" geschrieben, aber nicht, dass eine bestimmte Bibliothek einen Übersetzer für native Teile braucht. Auf meinem System war der zufällig installiert.

Der undokumentierte Zwischenschritt. Zwischen „Repository klonen" und „starten" lag bei mir ein Befehl, der die Datenbankstruktur anlegt. Für mich war das selbstverständlich, in der Anleitung stand es nicht. Die Fehlermeldung, die man ohne diesen Schritt bekommt, hilft nicht weiter.

Die stillschweigende Reihenfolge. Man muss die Konfiguration ausfüllen, bevor man startet. Ich wusste das. In meiner Anleitung standen beide Schritte, aber nicht, dass die Reihenfolge zwingend ist.

Was tatsächlich geholfen hat

Eine vollständige Beispielkonfiguration mit Kommentaren. Nicht eine Liste der Variablen, sondern eine Datei, in der bei jeder Zeile steht, was sie tut, ob sie Pflicht ist und wo man den Wert herbekommt.

# Pflicht. Der Token deiner Discord-Anwendung.
# Zu finden unter: Developer Portal > Deine App > Bot > Reset Token
DISCORD_TOKEN=

# Pflicht. Verbindungszeichenfolge zur Datenbank.
# Beispiel für lokales SQLite: file:./daten.db
DATABASE_URL=

# Optional. Ohne Redis läuft alles mit einem Zwischenspeicher im Arbeitsspeicher.
REDIS_URL=

Die dritte Zeile ist wichtiger, als sie aussieht: Optionale Dinge ausdrücklich als optional zu kennzeichnen, spart mehr Rückfragen als jede Erklärung.

Eine Prüfung beim Start. Statt mit einem unverständlichen Fehler abzustürzen, prüft die Anwendung ihre Konfiguration und sagt in klaren Worten, was fehlt:

[Konfiguration] DISCORD_TOKEN fehlt.
[Konfiguration] DATABASE_URL fehlt.
Bitte .env ausfüllen, Vorlage siehe .env.example.

Das war die Änderung mit dem größten Effekt auf die Zahl der Anfragen. Fast alle Startprobleme sind Konfigurationsprobleme.

Ein Abschnitt „Häufige Fehler" mit dem Wortlaut der Meldungen. Menschen suchen nach dem, was auf ihrem Bildschirm steht. Wer die Fehlermeldung wörtlich in die Dokumentation schreibt, wird gefunden.

Die unbequeme Seite

Es gibt einen Teil, den man ehrlich benennen muss: Self-Hosting anzubieten kostet dauerhaft Zeit, und zwar unabhängig davon, wie gut die Anleitung ist.

Jede Version bricht irgendwo etwas. Jede fremde Umgebung hat Besonderheiten. Und der Support für Leute, die nichts bezahlen, ist trotzdem Support — er hat nur keinen Rahmen.

Ich habe deshalb irgendwann eine klare Linie gezogen: Die Dokumentation beschreibt einen unterstützten Weg. Wer davon abweicht, kann das gerne tun, bekommt aber keine Hilfe bei Problemen, die aus der Abweichung stammen. Das klingt hart und war für beide Seiten entlastend — vorher habe ich stundenlang fremde Hosting-Umgebungen debuggt, die ich nicht kannte.

Die Gliederung, die tatsächlich funktioniert

Nach mehreren Umbauten sieht meine Dokumentation heute so aus — nach Zielen sortiert, nicht nach Bestandteilen:

Schnellstart. Der kürzeste Weg zu einem laufenden System, ohne Erklärungen. Wer nur ausprobieren will, ist hier fertig.

Installation. Derselbe Weg ausführlich, mit Voraussetzungen, Erklärungen und Prüfpunkten nach jedem Schritt.

Konfiguration. Jede Einstellung mit Beschreibung, Standardwert und Angabe, ob sie erforderlich ist.

Betrieb. Aktualisieren, sichern, umziehen, Protokolle lesen. Der Teil, den fast alle Anleitungen weglassen und den man am häufigsten braucht.

Häufige Fehler. Mit dem wörtlichen Text der Meldungen.

Die Reihenfolge ist Absicht: Sie folgt dem zeitlichen Ablauf einer Nutzung. Wer eine Software installiert, liest von oben nach unten — und wer sie seit einem Jahr betreibt, springt direkt in den vierten Abschnitt.

Was ich über Prüfpunkte gelernt habe

Der wirksamste Einzelbestandteil einer Anleitung ist nicht die Erklärung, sondern die Kontrolle: Woran erkenne ich, dass dieser Schritt geklappt hat?

Nach diesem Schritt sollte gelten:
- `pnpm start` gibt "Bereit auf Port 3000" aus
- ein Aufruf von http://localhost:3000/api/health antwortet mit {"status":"ok"}

Ohne solche Punkte macht man weiter, obwohl etwas fehlgeschlagen ist. Der Fehler taucht dann drei Schritte später an einer Stelle auf, die nichts damit zu tun hat — und die Rückfrage lautet „Schritt 7 funktioniert nicht", obwohl Schritt 4 das Problem war.

Ich schreibe deshalb inzwischen zuerst die Prüfpunkte und danach die Schritte dazwischen. Das klingt verkehrt herum und führt zu deutlich besseren Anleitungen, weil man dabei gezwungen ist, für jeden Schritt eine beobachtbare Wirkung zu benennen. Schritte ohne beobachtbare Wirkung sind entweder überflüssig oder falsch beschrieben.

Der Satz, der die meisten Tickets erspart hat

Eine einzige Ergänzung in der Anleitung hat mehr gebracht als jede Verbesserung am Text: eine ausdrückliche Angabe, welcher Weg unterstützt wird.

Getestet und unterstützt: Linux, Node in der angegebenen Fassung, der genannte Paketmanager, eine Datei-Datenbank. Andere Kombinationen funktionieren wahrscheinlich, aber ich kann bei Problemen nicht helfen.

Das klingt abweisend und wurde durchweg gut aufgenommen. Der Grund ist einfach: Es beantwortet eine Frage, die sich sonst jeder selbst stellt — nämlich, ob das eigene Setup vorgesehen ist.

Vorher habe ich Stunden damit verbracht, fremde Hosting-Umgebungen zu untersuchen, die ich nicht kannte. Nicht aus Hilfsbereitschaft, sondern weil ich keine Grenze gezogen hatte und jede Anfrage wie eine berechtigte Erwartung wirkte.

Eine ausgesprochene Grenze ist für beide Seiten entlastend. Der eine weiß, woran er ist, der andere muss nicht jedes Mal neu entscheiden, wie weit er geht.

Was ich daraus fürs Schreiben gelernt habe

Dokumentation ist kein Text über Software, sondern eine Anleitung für Menschen, die etwas erreichen wollen. Der Unterschied zeigt sich an der Gliederung: Nicht nach Komponenten sortieren („Der Bot", „Das Dashboard", „Die Datenbank"), sondern nach Zielen („Zum ersten Mal starten", „Auf einen neuen Server umziehen", „Auf eine neue Version aktualisieren").

Und jede Anleitung braucht einen Prüfpunkt: Woran erkenne ich, dass dieser Schritt geklappt hat? Ohne das weiß niemand, ob er weitermachen kann — und macht weiter, obwohl etwas fehlgeschlagen ist. Der Fehler taucht dann drei Schritte später auf, an einer Stelle, die nichts damit zu tun hat.