Ein Entwickler hat die These aufgestellt, dass das GitHub-Wiki eine schlechte Idee ist, und das Argument stützt sich auf einen einzigen vorgegebenen Vorteil: das Wiki ist immer da. Der Rest der These ist eine lange Liste von Beschwerden, die größtenteils darauf hinauslaufen, dass es sich um ein Wiki handelt.
Der Beitrag mit dem Titel „Das GitHub-Wiki ist ein Anti-Pattern“ zieht eine einfache Linie. Verwenden Sie das Wiki, wenn Sie eine Seite wünschen, die jeder von überall in Ihrem Repository mit einem einzigen Klick erreichen kann. Verwenden Sie einen Ordner /docs, wenn Sie eine Dokumentation wünschen, die mit Ihrem Code mitreist, wie Code begutachtet wird und lokal bleibt, wenn jemand Ihr Projekt klont.
Ein vorgegebener Vorteil
Der Autor beginnt mit einer Konzession: Es gibt einen Vorteil bei der Verwendung eines Wikis. Sie können auf den Wiki-Inhalt mit einem einzigen Klick von überall im Repository aus zugreifen. Das ist das gesamte Argument für die Existenz des Wikis.
Der Beitrag listet dann mehrere Gründe gegen das Wiki auf, darunter das Fehlen von Versionierung. Die Dokumentation wird nicht zusammen mit Ihrem Code versioniert, wenn Sie das Wiki verwenden, was bedeutet, dass alte Versionen der Dokumentation schwer zu finden sind. Das ist ein weiterer Grund gegen das Wiki, obwohl es als Nachteil und nicht als Vorteil dargestellt wird.
Warum Versionierung wichtig ist
Das stärkste Argument gegen das Wiki ist auch das einfachste. Die in einem Ordner /docs gespeicherte Dokumentation wandert mit Ihrem Code mit. Wenn Sie eine alte Version der Software verwenden müssen, sind die Dokumente leicht zu finden.
Der Beitrag weist außerdem darauf hin, dass Dokumentationsänderungen die gleiche Behandlung erfahren wie Code, wenn sie sich im Ordner /docs befinden. Sie durchlaufen den Pull-Request-Prozess, was bedeutet, dass sie einer vollständigen Peer-Review unterzogen werden. Das ist ein echter Unterschied zum Wiki, wo der Review-Prozess nicht existiert.
GitHub Actions können Dokumente in einem Ordner /docs mit Tools wie Vale überprüfen. Menschen können mit vertrauten Tools wie vscode mit Rechtschreibprüfung arbeiten. Der Ordner /docs unterstützt auch Bilder und individuelle Branding, obwohl dies im Beitrag nicht direkt erwähnt wird.
Dokumente aus dem Wiki verschieben
Der Beitrag bietet einen klaren Weg für alle, die vom Wiki wegwollen. Fügen Sie Ihre Dokumente Ihrem Repository im Ordner /docs hinzu. Verwenden Sie nicht den Branch gh-pages, da dies verhindert, dass Dokumente zusammen mit dem Code versioniert werden.
Richten Sie einen GitHub Pages Build ein, um die Dokumentation zu veröffentlichen. Wenn Sie gerade erst anfangen, empfiehlt der Autor, das just-the-docs Theme zu verwenden und GitHub Ihre Dokumentation automatisch erstellen und veröffentlichen zu lassen. Wenn Sie Ihren eigenen Workflow erstellen möchten, können Sie eine GitHub Action verwenden, um die Dokumentation zu veröffentlichen.
Der letzte Schritt ist einfach. Fügen Sie eine einzelne Wiki-Seite hinzu, die Benutzer auf die gehostete Dokumentation verweist. Auf diese Weise sehen alle, die auf den Wiki-Link klicken, eine Notiz, die sie auf die echte Dokumentation verweist.
Der Punkt, an dem es scheitert
Irgendwann werden die Dokumente einen einzelnen Ordner übersteigen. Dann ist alles egal. Sie werden ein separates Repo mit seinem eigenen Build-Prozess, Pull-Request-Review-Richtlinien und einer ganzen Reihe anderer Dinge wünschen.
Der Beitrag argumentiert, dass die Leute zu diesem Zeitpunkt bereits daran gewöhnt sind, mit Dokumenten in einem Repository zu arbeiten. Die Migration von /docs zu seinem eigenen Repo sollte für Mitwirkende nahtlos sein.
Das Anti-Pattern-Argument
Der Autor betrachtet die Verwendung des Wikis auf GitHub als Anti-Pattern. Der Beitrag macht diese Aussage, indem er viele weitere Gründe gegen die Verwendung des Wikis als Gründe für die Verwendung auflistet.
Das Wiki besteht diesen Test nicht, weil seine Vorteile gering sind und seine Nachteile sich häufen. Der Single-Click-Zugriff ist real, wird aber von allem anderen übertroffen. Das Fehlen von Versionierung, das fehlende Peer-Review, die begrenzte Branding – das sind keine Kleinigkeiten. Sie summieren sich zu einem System, das schwieriger zu warten ist und weniger nützlich als die Alternative.
Der Beitrag endet mit der Einladung an die Leser, ihre Gedanken auf Twitter zu teilen.
Wichtigste Fakten aus dem Beitrag
- Titel: „Das GitHub-Wiki ist ein Anti-Pattern“
- Plattform: GitHub
- Diskussion auslösend: Die Drei-Streiche-Regel (
- Kernbehauptung: Die Verwendung des Wikis ist ein Anti-Pattern (
Der Beitrag ist eine Art von humorlicher Ehrlichkeit. Der Autor konstruiert eine ganze Argumentation rund um zwei tatsächliche Vorteile – einen realen, einen impliziten – und eine Liste von Beanstandungen, die sich größtenteils darauf reduzieren, dass das Wiki ein Wiki ist. Das ist gleichzeitig lustig und ehrlich. (
Das Argument ist überzeugend, weil es spezifisch ist. Es vergleicht das Wiki mit einem /docs-Ordner nebeneinander, und die Unterschiede sind gravierend. Die Pull-Request-Überprüfung, das Linting, die lokale Verfügbarkeit – dies sind praktische Vorteile, die das Wiki einfach nicht bietet. (
Der Migrationspfad ist ebenfalls erwähnenswert. Der Autor behandelt den Übergang vom Wiki zum /docs-Ordner als natürliche Entwicklung, nicht als Störung. Das ist eine nützliche Einrahmung für alle, die einen Wechsel in Erwägung ziehen. (
Der Beitrag ist eine Erinnerung daran, dass das beste Werkzeug nicht immer das ist, das mit der Plattform mitgeliefert wird. Manchmal ist die integrierte Option die, die im Weg steht. In diesem Fall ist das Wiki das Problem, nicht die Lösung. (
Die Drei-Streiche-Regel des Autors bedeutet, dass dieses Argument schon seit einiger Zeit brodelt. Jetzt wurde es niedergeschrieben, und das Gespräch ist auf Twitter weitergezogen. Der /docs-Ordner lebt weiter. (
Quellenmaterial: „The GitHub wiki is an anti-pattern (2022),“ michaelheap.com. (
Das Notizbuch abonnieren.
Die besten Geschichten des Tages und jedes neue Urteil, in klarem Deutsch, um sieben im Postfach. Eine Mail am Tag, nicht mehr.