Vorheriges Tutorial: Developing Discourse Plugins - Part 6 - Add acceptance tests
Sie haben Ihr Plugin erstellt, es auf GitHub hochgeladen und Tests hinzugefügt. Großartig! Das Problem ist, dass niemand sonst davon weiß.
Dokumentation Ihres Plugins
Alle Plugins erfordern eine gute Dokumentation. Benutzer müssen wissen, was das Plugin tut, wie man es installiert, welche wichtigen Einstellungen/Konfigurationsänderungen erforderlich sind und wie man es verwendet. Plugins sollten an zwei verschiedenen Stellen dokumentiert werden: in der Datei README.md in Ihrem Git-Repository und in einem speziellen Thema in der Kategorie Plugin.
GitHub-Dokumentation
Die Datei README.md auf GitHub ist wichtig, da sie standardmäßig angezeigt wird, wenn ein Benutzer Ihr Repository besucht. Mindestens sollte Ihre Readme den Titel des Plugins und eine kurze Beschreibung enthalten. Eine vollständigere Readme enthält auch Installationsanweisungen, eine detailliertere Beschreibung, grundlegende Nutzungshinweise, Lizenz und (falls zutreffend) Screenshots. Wenn zusätzliche Anweisungen im Meta-Thema Ihres Plugins enthalten sind, stellen Sie sicher, dass Sie einen Link zu diesem Thema einfügen.
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.
Beispiel-Plugin-README-Vorlage
Stellen Sie sicher, dass Sie Text, der von < und > umschlossen ist, mit Ihren Plugin-Spezifika aktualisieren.
## <Plugin Title>
<Plugin Description>
## Installation
Folgen Sie der [Plugin-Installationsanleitung](https://meta.discourse.org/t/install-a-plugin/19157).
## Verwendung
<Erklären Sie, wie das Plugin aktiviert wird, welche notwendigen Konfigurationsschritte erforderlich sind und wie es verwendet wird>
## Screenshots
<Fügen Sie bei Bedarf Screenshots hinzu, um die Verwendung Ihres Plugins zu demonstrieren>
## Weiterführende Informationen
<Fügen Sie einen Link zu Ihrem Meta-Thema ein, falls dort weitere Informationen detailliert sind>
## Lizenz
<Geben Sie Ihre Code-Lizenz an, die meisten Discourse-Plugins verwenden MIT>
Meta-Dokumentation
Während die GitHub-Dokumentation tendenziell kurz und „auf den Punkt“ ist, können Sie im Meta-Bereich die vollständigen Details Ihres Plugins mitteilen und Benutzer davon überzeugen, warum sie es verwenden sollten. Mindestens sollte Ihr Meta-Thema eine kurze Beschreibung des Plugins und einen Link zum Repository des Plugins auf GitHub enthalten (damit Benutzer es installieren können). Eine vollständigere Dokumentation enthält auch eine detaillierte Beschreibung mit Anwendungsbeispielen, detaillierte Nutzungshinweise, Dokumentation aller Einstellungen und Konfigurationsoptionen sowie Screenshots. Screenshots sind entscheidend, da Benutzer sehen möchten, was Ihr Plugin tut, und nicht nur darüber lesen wollen. 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, recht viele davon haben sollte.
Die Meta-Dokumentation ist tendenziell persönlicher als GitHub; jeder Plugin-Autor hat seinen eigenen Dokumentationsstil. Welchen Stil Sie auch wählen, stellen Sie sicher, dass er klar, leicht lesbar und organisiert ist. Verwenden Sie Überschriften nach Bedarf, kommentieren Sie Screenshots, um komplexe Interaktionen zu erklären, und achten Sie auf Konsistenz in Ihrer Formatierung. Widerstehen Sie der Versuchung, einen einzigen großen Absatz zu schreiben.
Aktualisierung Ihrer Dokumentation
Nachdem Sie Ihre anfängliche Dokumentation verfasst haben, ist es wichtig, sie aktuell zu halten.
Eine neue Funktion zum Plugin hinzugefügt? Nehmen Sie sich auf jeden Fall etwas Zeit, um sie zu dokumentieren.
Dieselbe Frage mehrmals beantwortet? Ziehen Sie in Betracht, Ihrem Meta-Thema einen FAQ-Bereich hinzuzufügen.
Bekanntes Problem, das kompliziert zu beheben ist? Beschreiben Sie es in Ihrem Thema, damit die Benutzer wissen, was sie erwartet.
Unterstützung Ihres Plugins
Nachdem Sie Ihr Plugin und seine Dokumentation veröffentlicht haben, können Site-Administratoren, die es nützlich finden, es auf ihrer Site installieren und mit der Nutzung beginnen. Diese Nutzung erfordert laufende Unterstützung durch den Plugin-Entwickler. Sie sollten Fragen beantworten, die Site-Administratoren haben, und ihnen bei der Verwendung Ihres Plugins helfen. Was Ihnen perfekt erschien, kann für andere unklar sein, daher sollten Sie den Code und/oder die Dokumentation aktualisieren, um dies zu verdeutlichen. Möglicherweise erhalten Sie Funktionsanfragen, über deren Hinzufügung Sie entscheiden müssen.
Zuletzt wird Discourse selbst ständig weiterentwickelt. Während Ihr Plugin heute perfekt funktionieren mag, könnte sich morgen etwas ändern, das es außer Kraft setzt. Stellen Sie sicher, dass Sie über die Entwicklung von Discourse auf dem Laufenden bleiben, damit Sie Ihr Plugin aktualisieren können, um die neueste Version von Discourse zu unterstützen, wenn eine Änderung Ihr Plugin betrifft.
Mehr in dieser Serie
Teil 1: Plugin-Grundlagen
Teil 2: Plugin-Outlets
Teil 3: Site-Einstellungen
Teil 4: Git-Setup
Teil 5: Admin-Schnittstellen
Teil 6: Akzeptanztests
Teil 7: Dieses Thema
Dieses Dokument wird versioniert – schlagen Sie Änderungen auf GitHub vor.
