Vorheriges Tutorial: Developing Discourse Plugins - Part 6 - Add acceptance tests
Du hast dein Plugin erstellt, es auf GitHub hochgeladen und Tests hinzugefügt. Super! Das Problem ist nur, dass noch niemand davon weiß.
Dein Plugin dokumentieren
Alle Plugins benötigen eine gute Dokumentation. Die Nutzer müssen wissen, was das Plugin macht, wie es installiert wird, welche wichtigen Einstellungen/Änderungen der Konfiguration erforderlich sind und wie man es verwendet. Plugins sollten an zwei verschiedenen Stellen dokumentiert werden: in der Datei README.md in deinem Git-Repository und in einem eigenen Thema in der Kategorie Customization > Plugin.
Dokumentation auf GitHub
Die Datei README.md auf GitHub ist wichtig, da sie standardmäßig angezeigt wird, wenn ein Benutzer dein Repository besucht. Deine README-Datei sollte mindestens den Titel des Plugins und eine kurze Beschreibung enthalten. Eine vollständigere README-Datei enthält auch Installationsanweisungen, eine detailliertere Beschreibung, grundlegende Bedienungsanweisungen, die Lizenz und (falls zutreffend) Screenshots. Wenn in deinem Meta-Thema zusätzliche Anweisungen enthalten sind, füge unbedingt einen Link zum Thema hinzu.
Beispiel für ein minimal dokumentiertes Plugin: Discourse Data Explorer
Beispiele für Plugins mit vollständigerer Dokumentation: Discourse Solved, Discourse OAuth2 Basic und Discourse Ads.
Beispielvorlage für die README-Datei eines Plugins
Achte darauf, den Text, der von < > umgeben ist, durch die spezifischen Daten deines Plugins zu ersetzen.
## <Plugin-Titel>
<Plugin-Beschreibung>
## Installation
Befolge die [Anleitung zur Plugin-Installation](https://meta.discourse.org/t/install-a-plugin/19157).
## Verwendung
<Erkläre, wie das Plugin aktiviert wird, die erforderlichen Konfigurationsschritte und wie man es verwendet>
## Screenshots
<Inkludiere Screenshots, falls diese zur Veranschaulichung der Verwendung deines Plugins erforderlich sind>
## Mehr dazu
<Inkludiere einen Link zu deinem Meta-Thema, falls dort weitere Informationen enthalten sind>
## Lizenz
<Gib deine Code-Lizenz an, die meisten Discourse-Plugins verwenden die MIT-Lizenz>
Dokumentation auf Meta
Während die Dokumentation auf GitHub tendenziell kurz und „auf den Punkt“ ist, kannst du in der Dokumentation auf Meta die vollständigen Details deines Plugins teilen und die Nutzer davon überzeugen, warum sie es verwenden sollten. Dein Meta-Thema sollte mindestens eine kurze Beschreibung des Plugins und einen Link zum Repository des Plugins auf GitHub enthalten (damit die Nutzer es installieren können). Eine vollständigere Dokumentation enthält außerdem eine detaillierte Beschreibung mit Beispielen für Anwendungsfälle, detaillierte Bedienungsanweisungen, eine Dokumentation aller Einstellungen und Konfigurationsoptionen sowie Screenshots. Screenshots sind entscheidend, da Nutzer sehen möchten, was dein Plugin macht, und nicht nur darüber lesen möchten. Ein Plugin, das einen Authentifizierungsanbieter hinzufügt, benötigt wahrscheinlich nur einen Screenshot, während ein Plugin, das eine neue Benutzeroberfläche hinzufügt oder größere Änderungen vornimmt, deutlich mehr Screenshots enthalten sollte.
Die Dokumentation auf Meta ist tendenziell persönlicher als auf GitHub; jeder Plugin-Autor hat seinen eigenen Dokumentationsstil. Welchen Stil du auch wählst, stelle sicher, dass er klar, leicht zu lesen und gut strukturiert ist. Verwende Überschriften, wo es angebracht ist, kommentiere Screenshots, um komplexe Interaktionen zu erklären, und achte auf eine konsistente Formatierung. Widerstehe der Versuchung, einen einzigen riesigen Absatz zu schreiben.
Aktualisierung deiner Dokumentation
Nachdem du deine erste Dokumentation geschrieben hast, ist es wichtig, diese auf dem neuesten Stand zu halten.
Hast du dem Plugin eine neue Funktion hinzugefügt? Nimm dir unbedingt etwas Zeit, um sie zu dokumentieren.
Hast du dieselbe Frage mehrmals beantwortet? Überlege, eine FAQ-Sektion zu deinem Meta-Thema hinzuzufügen.
Gibt es ein bekanntes Problem, das sich nur schwer beheben lässt? Beschreibe es in deinem Thema, damit die Nutzer wissen, was sie erwarten können.
Support für dein Plugin
Nachdem du dein Plugin und seine Dokumentation veröffentlicht hast, werden Site-Administratoren, die es nützlich finden, es möglicherweise auf ihrer Site installieren und verwenden. Diese Nutzung erfordert einen laufenden Support durch den Plugin-Entwickler. Du wirst Fragen der Site-Administratoren beantworten und ihnen bei der Verwendung deines Plugins helfen müssen. Etwas, das für dich absolut sinnvoll war, kann für andere unklar sein, daher wirst du den Code und/oder die Dokumentation aktualisieren müssen, um es zu erläutern. Du könntest Feature-Anfragen erhalten, bei denen du entscheiden musst, ob du sie umsetzen möchtest.
Schließlich befindet sich Discourse selbst in ständiger Entwicklung. Während dein Plugin heute möglicherweise einwandfrei funktioniert, könnte sich morgen etwas ändern, das es zum Absturz bringt. Achte darauf, dich über die Entwicklung von Discourse auf dem Laufenden zu halten, damit du dein Plugin aktualisieren kannst, um die neueste Version von Discourse zu unterstützen, wenn eine Änderung dein Plugin betrifft.
Mehr in der Serie
Teil 1: Grundlagen von Plugins
Teil 2: Plugin-Ausgabeorte
Teil 3: Site-Einstellungen
Teil 4: Git-Einrichtung
Teil 5: Admin-Oberflächen
Teil 6: Akzeptanztests
Teil 7: Dieses Thema
Dieses Dokument ist versionskontrolliert – schlage Änderungen auf GitHub vor.
