Tutoriel précédent : Developing Discourse Plugins - Part 6 - Add acceptance tests
Vous avez créé votre plugin, vous l’avez téléchargé sur GitHub et vous y avez ajouté des tests. Excellent ! Le problème, c’est que personne d’autre n’en sait rien.
Documenter votre plugin
Tous les plugins nécessitent une bonne documentation. Les utilisateurs doivent savoir ce que fait le plugin, comment l’installer, les modifications de paramètres/configuration importantes nécessaires, et comment l’utiliser. Les plugins doivent être documentés à deux endroits différents : le fichier README.md dans votre dépôt git, et un sujet dédié dans la catégorie Customization > Plugin.
Documentation GitHub
Le fichier README.md sur GitHub est important car il est affiché par défaut lorsqu’un utilisateur visite votre dépôt. Au minimum, votre readme doit inclure le titre du plugin et une brève description. Un readme plus complet inclura également des instructions d’installation, une description plus détaillée, des instructions d’utilisation de base, la licence, et (le cas échéant) des captures d’écran. Si des instructions supplémentaires sont incluses dans le sujet Meta de votre plugin, assurez-vous d’y inclure un lien.
Exemple de plugin faiblement documenté : Discourse Data Explorer
Exemples de plugins avec une documentation plus complète : Discourse Solved, Discourse OAuth2 Basic, et Discourse Ads.
Modèle de README pour plugin
N’oubliez pas de mettre à jour le texte entouré de < > avec les spécificités de votre plugin.
## <Titre du plugin>
<Description du plugin>
## Installation
Suivez le [guide d'installation des plugins](https://meta.discourse.org/t/install-a-plugin/19157).
## Comment utiliser
<Expliquez comment activer le plugin, les étapes de configuration nécessaires, et comment l'utiliser>
## Captures d'écran
<Incluez des captures d'écran si nécessaire pour démontrer l'utilisation de votre plugin>
## En savoir plus
<Incluez un lien vers votre sujet Meta si plus de détails y sont fournis>
## Licence
<Indiquez la licence de votre code, la plupart des plugins Discourse utilisent la licence MIT>
Documentation Meta
Là où la documentation GitHub tend à être courte et « à l’essentiel », la documentation Meta est l’endroit où vous pouvez partager tous les détails de votre plugin et convaincre les utilisateurs de l’utiliser. Au minimum, votre sujet Meta doit inclure une brève description du plugin et un lien vers le dépôt GitHub du plugin (pour que les utilisateurs puissent l’installer). Une documentation plus complète inclura également une description détaillée avec des exemples de cas d’utilisation, des instructions d’utilisation détaillées, la documentation de tous les paramètres et options de configuration, ainsi que des captures d’écran. Les captures d’écran sont essentielles car les utilisateurs veulent voir ce que fait votre plugin, pas seulement en lire la description. Un plugin ajoutant un fournisseur d’authentification n’aura probablement besoin que d’une seule capture d’écran, tandis qu’un plugin ajoutant une nouvelle interface ou apportant des modifications majeures devrait en contenir plusieurs.
La documentation Meta tend à être plus personnelle que celle de GitHub, chaque auteur de plugin ayant son propre style de documentation. Quel que soit le style que vous choisissez, assurez-vous qu’il soit clair, facile à lire et bien organisé. Utilisez des en-têtes appropriés, annoter les captures d’écran pour expliquer les interactions complexes, et veillez à être cohérent dans votre mise en forme. Évitez la tentation d’écrire un seul paragraphe géant.
Mettre à jour votre documentation
Après avoir rédigé votre documentation initiale, il est important de la maintenir à jour.
Vous avez ajouté une nouvelle fonctionnalité au plugin ? Prenez le temps de la documenter.
Vous avez répondu à la même question plusieurs fois ? Envisagez d’ajouter une section FAQ à votre sujet Meta.
Un problème connu qui est complexe à corriger ? Détaillez-le dans votre sujet pour que les utilisateurs sachent à quoi s’attendre.
Soutenir votre plugin
Après avoir publié votre plugin et sa documentation, les administrateurs de site qui le jugeront utile pourront l’installer sur leur site et commencer à l’utiliser. Cette utilisation nécessite un support continu de la part du développeur du plugin. Vous devrez répondre aux questions des administrateurs de site, les aidant à utiliser votre plugin. Ce qui vous semblait évident peut être peu clair pour d’autres, vous devrez donc mettre à jour le code et/ou la documentation pour l’éclaircir. Vous pourriez recevoir des demandes de fonctionnalités, auxquelles vous devrez décider si vous souhaitez répondre ou non.
Enfin, Discourse lui-même est en développement constant. Bien que votre plugin fonctionne parfaitement aujourd’hui, quelque chose pourrait changer demain et le faire dysfonctionner. Assurez-vous de rester informé du développement de Discourse afin de pouvoir mettre à jour votre plugin pour qu’il soit compatible avec la dernière version de Discourse lorsqu’un changement affecte votre plugin.
Plus dans la série
Partie 1 : Bases des plugins
Partie 2 : Sorties de plugins
Partie 3 : Paramètres du site
Partie 4 : Configuration git
Partie 5 : Interfaces d’administration
Partie 6 : Tests d’acceptation
Partie 7 : Ce sujet
Ce document est versionné - suggérez des modifications sur GitHub.
