Das Wiki ist das Pflichtenheft
Bevor ich ein zentrales Plugin baue, das dutzende ersetzen soll, muss ich wissen, was das Netzwerk heute tatsächlich tut. Warum die Dokumentation vor dem Code kommt — und wie ich fast anders entschieden hätte.
Blackzack985 Wörter · 5 Min. Lesezeit
- doku
- planung
- minecraft
Der Plan steht seit einer Woche: ein eigenes zentrales Plugin, das einen großen Teil der fremden Plugins ersetzt. Die Frage war, womit man anfängt.
Mein Vorschlag war: ein Gerüst bauen und einen einzelnen Gegenstand vollständig durchziehen — Java und Bedrock, von der Definition bis zur Darstellung. Damit hat man einen belegten Weg und kann daran alles Weitere hängen.
Die Entscheidung war eine andere: zuerst ein vollständiges Wiki. Alle Menüs, alle Befehle, alle Funktionen für Spieler, Moderatoren und Verwaltung. Alle Rechte. Alle Kaufmöglichkeiten. Im Detail, so dass nichts fehlt.
Und ausdrücklich nur das, was tatsächlich benutzt wird — nicht das, was die installierten Plugins theoretisch könnten.
Ich halte das inzwischen für die richtige Reihenfolge, und der Grund dafür ist ein Satz, der mir beim Nachdenken darüber sehr klar geworden ist.
Das Wiki ist das Pflichtenheft
Ein Plugin, das ein bestehendes Verhalten ersetzen soll, muss dieses Verhalten reproduzieren. Und niemand kann sagen, was das Netzwerk heute tut — nicht vollständig.
Es sind über fünfzig Plugins, gewachsen über Wochen, teilweise aus einem gekauften Paket, teilweise dazugekommen, teilweise umkonfiguriert. Was davon aktiv genutzt wird, was nur mitläuft, welche Menüs die Spieler tatsächlich öffnen — das steht nirgends.
Ohne diese Beschreibung würde ich ein Plugin bauen, das meine Vorstellung vom Netzwerk abbildet. Und die Lücke zwischen Vorstellung und Wirklichkeit merkt man dann, wenn jemand einen Befehl benutzt, den es nicht mehr gibt.
Warum ich zuerst anders wollte
Ich schreibe das auf, weil mein Vorschlag nicht falsch war — er war für eine andere Frage richtig.
Mit einem Gerüst und einem durchgezogenen Beispiel beantwortet man die Frage: Geht das technisch, und wie viel Aufwand ist ein Element? Das ist wertvoll, wenn die Machbarkeit unklar ist.
Hier ist die Machbarkeit nicht die Unsicherheit. Die Unsicherheit ist der Umfang. Und bei einer Umfangsfrage hilft ein technischer Durchstich wenig — er beantwortet, wie teuer ein Element ist, nicht wie viele es sind.
Das ist eine Unterscheidung, die ich mir gemerkt habe: Erst klären, welche Sorte Unsicherheit man hat. Technische Unsicherheit löst man mit einem Prototyp. Umfangsunsicherheit löst man mit einer Bestandsaufnahme.
Was so ein Wiki leisten muss
Es beschreibt Verhalten, nicht Konfiguration. Nicht „Plugin X ist installiert", sondern: Was passiert, wenn ein Spieler diesen Befehl eingibt? Was steht in diesem Menü? Welche Bedingung muss erfüllt sein?
Es unterscheidet nach Rolle. Was ein Spieler sieht, ist etwas anderes als das, was ein Moderator sieht.
Es benennt, was tatsächlich benutzt wird. Das ist die schwierigste Anforderung, weil sie eine Messung verlangt. Ein Menüpunkt, den in drei Monaten niemand angeklickt hat, gehört auf die Liste der Dinge, die man beim Neubau weglassen kann.
Es ist vollständig genug, dass man daraus bauen kann. Das ist der Prüfstein: Könnte jemand, der das Netzwerk nicht kennt, mit diesem Dokument ein System bauen, das sich für Spieler gleich anfühlt?
Der angenehme Nebeneffekt
Ein solches Dokument ist nicht nur ein Pflichtenheft. Es ist gleichzeitig:
- Die Anleitung für Spieler. Was kann ich hier tun?
- Das Handbuch für Moderatoren. Was darf ich, und wie mache ich es?
- Die Übergabe an jeden, der jemals mithilft.
- Die Grundlage für jede Entscheidung darüber, was wegfällt.
Der letzte Punkt ist der, der mich überzeugt hat. Beim Aufschreiben stellt man automatisch die Frage, ob etwas gebraucht wird — und beantwortet damit die Reduktionsfrage, bevor eine Zeile Code entsteht.
Infobox
Das ist derselbe Effekt, den ich vor Jahren beim Auswerten meiner Bot-Befehle hatte. Sobald man aufschreibt, was es alles gibt, sieht man, wie viel davon niemand benutzt. Die Liste ist die Diagnose, das Aufräumen die Folge — und beides passiert vor dem Bauen, nicht danach.
Wie ich die Dokumentation aufgebaut habe
Ein vollständiges Wiki über ein gewachsenes System zu schreiben, klingt nach einer unlösbaren Aufgabe. Was geholfen hat, war eine Gliederung nach Rollen und Situationen statt nach Technik.
Was ein Spieler tun kann. Alle Befehle, alle Menüs, alle Wege — beschrieben aus seiner Sicht, ohne Plugin-Namen.
Was ein Moderator zusätzlich kann. Und mit welchem Recht.
Was die Verwaltung kann. Inklusive der Vorgänge, die nur selten anfallen.
Wie die Wirtschaft funktioniert. Währungen, Läden, Preise, Wege, auf denen Geld entsteht und verschwindet.
Welche eigenen Inhalte es gibt. Gegenstände, Modelle, Pakete — und für welche Spielfassung sie gelten.
Wie das Netzwerk aufgebaut ist. Eingang, Server, Wechselwege, was wo läuft.
Die Beschreibung aus Sicht der Rolle ist der Schlüssel. Eine Dokumentation nach Plugins gegliedert ist eine Liste dessen, was installiert ist — und beantwortet nicht die Frage, was ein Neubau können muss.
Was mir beim Schreiben aufgefallen ist
Die Übung hatte einen Nebeneffekt, mit dem ich nicht gerechnet hatte: Ich habe beim Aufschreiben Dinge gefunden, die nicht funktionieren.
Ein Menüpunkt, der auf eine Funktion verweist, die es nicht mehr gibt. Ein Recht, das vergeben wird, aber nirgends geprüft. Ein Gutschein, der eine Berechtigung für ein Plugin gibt, das gar nicht läuft. Eine Beschreibung, die eine andere Preisstufe nennt als die tatsächliche.
Das ist keine besondere Leistung — es ist die zwangsläufige Folge davon, jedes Element einmal ausdrücklich zu benennen. Wer beschreibt, was passieren soll, vergleicht automatisch mit dem, was passiert.
Ich halte das inzwischen für den unterschätztesten Nutzen von Dokumentation: Sie ist eine Prüfung des Systems, verkleidet als Schreibarbeit. Und sie findet Dinge, die kein Test findet, weil Tests nur prüfen, woran jemand gedacht hat.
Die ehrliche Größenordnung
Ich habe angefangen und bin bei einem Umfang gelandet, der mich selbst überrascht hat: ein fünfstelliger Zeichenumfang über mehrere Dokumente — Rollen und Rechte, eigene Plugins, Wirtschaft und Läden, eigene Inhalte, Spielwelt und Schutz, Chat und Anzeige, Bedrock und Crossplay, Lobby und Proxy.
Und das ist der Stand für ein Netzwerk, das seit wenigen Wochen läuft.
Das ist die Zahl, die ich mir merke, wenn ich das nächste Mal denke, ein System sei überschaubar. Was man im Kopf hat, ist immer eine Zusammenfassung. Die Wirklichkeit steht in den Details, und die Details sind der Grund, warum ein Neubau länger dauert als der ursprüngliche Aufbau.