Tutoriel précédent : Developing Discourse Plugins - Part 6 - Add acceptance tests
Vous avez créé votre plugin, vous l’avez téléversé sur GitHub et vous avez ajouté des tests. Excellent ! Le problème est que personne d’autre n’est au courant.
Documenter votre plugin
Tous les plugins nécessitent une bonne documentation. Les utilisateurs doivent savoir ce que fait le plugin, comment l’installer, quelles sont les modifications importantes de paramètres/configuration 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 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 courte 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 (si applicable) des captures d’écran. Si des instructions supplémentaires sont incluses dans le sujet Meta de votre plugin, assurez-vous d’inclure un lien vers ce sujet.
Exemple de plugin minimalement 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 de plugin
Assurez-vous de mettre à jour le texte entouré de \u003c\u003e avec les spécificités de votre plugin.
## \u003cTitre du Plugin\u003e
\u003cDescription du Plugin\u003e
## Installation
Suivez le [guide d'installation des plugins](https://meta.discourse.org/t/install-a-plugin/19157).
## Comment l'utiliser
\u003cExpliquez comment activer le plugin, les étapes de configuration nécessaires et comment l'utiliser\u003e
## Captures d'écran
\u003cIncluez des captures d'écran si nécessaire pour démontrer l'utilisation de votre plugin\u003e
## Lire plus
\u003cIncluez un lien vers votre sujet Meta si plus d'informations y sont détaillées\u003e
## Licence
\u003cMentionnez la licence de votre code, la plupart des plugins Discourse utilisent MIT\u003e
Documentation Meta
Là où la documentation GitHub tend à être courte et « directe », la documentation Meta est l’endroit où vous pouvez partager tous les détails de votre plugin et convaincre les utilisateurs pourquoi ils devraient l’utiliser. Au minimum, votre sujet Meta doit inclure une courte description du plugin et un lien vers le dépôt du plugin sur GitHub (afin que les utilisateurs puissent l’installer). Une documentation plus complète inclura également une description détaillée incluant des exemples de cas d’utilisation, des instructions d’utilisation détaillées, la documentation de tous les paramètres et options de configuration, et des captures d’écran. Les captures d’écran sont essentielles car les utilisateurs veulent voir ce que fait votre plugin, pas seulement lire à son sujet. Un plugin ajoutant un fournisseur d’authentification n’aura probablement besoin que d’une seule capture d’écran, tandis qu’un plugin qui ajoute une nouvelle interface ou apporte des modifications majeures devrait en avoir beaucoup plus.
La documentation Meta a tendance à être plus personnelle que celle de GitHub ; chaque auteur de plugin a son propre style de documentation. Quel que soit le style que vous choisissez, assurez-vous qu’il est clair, facile à lire et organisé. Utilisez des en-têtes comme il convient, annotez les captures d’écran pour expliquer les interactions complexes, et soyez cohérent dans votre formatage. Évitez la tentation d’écrire un seul grand paragraphe.
Mise à jour de 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 ? Assurez-vous de prendre le temps de la documenter.
Vous avez répondu plusieurs fois à la même question ? Envisagez d’ajouter une section FAQ à votre sujet Meta.
Un problème connu qui est compliqué à résoudre ? Détaillez-le dans votre sujet afin 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 trouvent utile peuvent l’installer sur leur site et commencer à l’utiliser. Cette utilisation nécessite un soutien continu de la part du développeur du plugin. Vous voudrez répondre aux questions que les administrateurs de site se posent, en les aidant à utiliser votre plugin. Quelque chose qui vous semblait parfaitement clair peut être obscur pour d’autres, vous voudrez donc mettre à jour le code et/ou la documentation pour clarifier cela. Vous pourriez recevoir des demandes de fonctionnalités, que vous devrez décider d’ajouter ou non.
Enfin, Discourse lui-même est en développement constant. Bien que votre plugin puisse fonctionner parfaitement aujourd’hui, demain quelque chose pourrait changer et le casser. Assurez-vous de rester à jour sur le développement de Discourse afin de pouvoir mettre à jour votre plugin pour prendre en charge 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 plugin (Plugin Outlets)
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 contrôlé par version - suggérez des modifications sur github.
