Tutorial anterior: Developing Discourse Plugins - Part 6 - Add acceptance tests
¡Has creado tu plugin, lo has subido a GitHub y has añadido pruebas. ¡Genial! El problema es que nadie más lo sabe.
Documentar tu plugin
Todos los plugins requieren una buena documentación. Los usuarios necesitan saber qué hace el plugin, cómo instalarlo, qué cambios importantes de configuración/ajustes son necesarios y cómo usarlo. Los plugins deben documentarse en dos lugares diferentes: el archivo README.md dentro de tu repositorio git y un tema dedicado en la categoría Plugin.
Documentación de GitHub
El archivo README.md en GitHub es importante ya que se muestra por defecto cuando un usuario visita tu repositorio. Como mínimo, tu readme debe incluir el título del plugin y una breve descripción. Un readme más completo también incluirá instrucciones de instalación, una descripción más detallada, instrucciones básicas de uso, licencia y (si corresponde) capturas de pantalla. Si se incluyen instrucciones adicionales en el tema de Meta de tu plugin, asegúrate de incluir un enlace a dicho tema.
Ejemplo de un plugin mínimamente documentado: Discourse Data Explorer
Ejemplos de plugins con documentación más completa: Discourse Solved, Discourse OAuth2 Basic y Discourse Ads.
Plantilla de README de ejemplo para plugin
Asegúrate de actualizar el texto rodeado de \u003c\u003e con los detalles específicos de tu plugin.
## \u003cTítulo del Plugin\u003e
\u003cDescripción del Plugin\u003e
## Instalación
Sigue la [guía de instalación de plugins](https://meta.discourse.org/t/install-a-plugin/19157).
## Cómo usar
\u003cExplica cómo habilitar el plugin, los pasos de configuración necesarios y cómo usarlo\u003e
## Capturas de pantalla
\u003cIncluye capturas de pantalla si es necesario para demostrar el uso de tu plugin\u003e
## Leer más
\u003cIncluye un enlace a tu tema de Meta si hay más información detallada allí\u003e
## Licencia
\u003cIndica la licencia de tu código, la mayoría de los plugins de Discourse usan MIT\u003e
Documentación de Meta
Mientras que la documentación de GitHub tiende a ser breve y “al grano”, la documentación de Meta es donde puedes compartir todos los detalles de tu plugin y convencer a los usuarios de por qué deberían usarlo. Como mínimo, tu tema de Meta debe incluir una breve descripción del plugin y un enlace al repositorio del plugin en GitHub (para que los usuarios puedan instalarlo). Una documentación más completa también incluirá una descripción detallada con casos de uso de ejemplo, instrucciones de uso detalladas, documentación de todas las opciones de configuración y ajustes, y capturas de pantalla. Las capturas de pantalla son clave ya que los usuarios quieren ver lo que hace tu plugin, no solo leer sobre ello. Un plugin que añade un proveedor de autenticación probablemente necesite solo 1 captura de pantalla, mientras que un plugin que añade una nueva interfaz o realiza cambios importantes debería tener bastantes más.
La documentación de Meta tiende a ser más personal que la de GitHub; cada autor de plugin tiene su propio estilo de documentación. Sea cual sea el estilo que elijas, asegúrate de que sea claro, fácil de leer y organizado. Utiliza encabezados según corresponda, anota las capturas de pantalla para explicar interacciones complejas y asegúrate de ser consistente en tu formato. Evita la tentación de escribir un único párrafo gigante.
Actualizar tu documentación
Después de escribir tu documentación inicial, es importante mantenerla actualizada.
¿Añadiste una nueva funcionalidad al plugin? Asegúrate de dedicar algo de tiempo a documentarla.
¿Respondiste la misma pregunta varias veces? Considera añadir una sección de Preguntas Frecuentes a tu tema de Meta.
¿Problema conocido que es complicado de solucionar? Detállalo en tu tema para que los usuarios sepan qué esperar.
Dar soporte a tu plugin
Después de publicar tu plugin y su documentación, los administradores de sitios que lo encuentren útil pueden instalarlo en su sitio y comenzar a usarlo. Este uso requiere soporte continuo por parte del desarrollador del plugin. Querrás responder a las preguntas que tengan los administradores del sitio, ayudándoles a usar tu plugin. Algo que tuvo perfecto sentido para ti puede no ser claro para otros, por lo que querrás actualizar el código y/o la documentación para aclararlo. Es posible que recibas solicitudes de nuevas funcionalidades, las cuales tendrás que decidir si añadirlas o no.
Por último, Discourse en sí mismo está en constante desarrollo. Si bien tu plugin puede funcionar perfectamente hoy, mañana algo podría cambiar y romperlo. Asegúrate de mantenerte al día con el desarrollo de Discourse para que puedas actualizar tu plugin para que sea compatible con la última versión de Discourse cuando un cambio afecte a tu plugin.
Más en la serie
Parte 1: Conceptos básicos de plugins
Parte 2: Salidas de plugins
Parte 3: Ajustes del sitio
Parte 4: Configuración de git
Parte 5: Interfaces de administrador
Parte 6: Pruebas de aceptación
Parte 7: Este tema
Este documento está controlado por versiones: sugiere cambios en github.
