Tutorial anterior: Developing Discourse Plugins - Part 6 - Add acceptance tests
Ya has creado tu plugin, lo has subido a GitHub y le has añadido pruebas. ¡Genial! El problema es que nadie más sabe de su existencia.
Documentar tu plugin
Todos los plugins requieren una buena documentación. Los usuarios necesitan saber qué hace el plugin, cómo instalarlo, los cambios importantes de configuración que sean necesarios y cómo utilizarlo. 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 Customization > Plugin.
Documentación en 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, la licencia y (si procede) capturas de pantalla. Si se incluyen instrucciones adicionales en el tema de Meta de tu plugin, asegúrate de incluir un enlace al tema.
Ejemplo de un plugin con documentación mínima: Discourse Data Explorer
Ejemplos de plugins con documentación más completa: Discourse Solved, Discourse OAuth2 Basic y Discourse Ads.
Plantilla de README de plugin de ejemplo
Asegúrate de actualizar el texto rodeado por < > con los detalles específicos de tu plugin.
## <Título del plugin>
<Descripción del plugin>
## Instalación
Sigue la [guía de instalación de plugins](https://meta.discourse.org/t/install-a-plugin/19157).
## Cómo usarlo
<Explica cómo habilitar el plugin, los pasos de configuración necesarios y cómo utilizarlo>
## Capturas de pantalla
<Incluye capturas de pantalla si es necesario para demostrar el uso de tu plugin>
## Leer más
<Incluye un enlace a tu tema de Meta si se detallan más información allí>
## Licencia
<Indica la licencia de tu código, la mayoría de los plugins de Discourse usan MIT>
Documentación en 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 ejemplos de casos de uso, 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 qué hace tu plugin, no solo leer al respecto. Un plugin que añade un proveedor de autenticación probablemente solo necesite 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. Cualquiera que sea el estilo que elijas, asegúrate de que sea claro, fácil de leer y organizado. Utiliza encabezados cuando corresponda, anota las capturas de pantalla para explicar interacciones complejas y asegúrate de ser constante en tu formato. Evita la tentación de escribir un solo párrafo gigante.
Actualizar tu documentación
Después de escribir tu documentación inicial, es importante mantenerla actualizada.
¿Has añadido una nueva función al plugin? Asegúrate de reservar algo de tiempo para documentarla.
¿Has respondido la misma pregunta varias veces? Considera añadir una sección de preguntas frecuentes (FAQ) a tu tema de Meta.
¿Hay un problema conocido que es complicado de corregir? 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 un soporte continuo por parte del desarrollador del plugin. Querrás responder a las preguntas que tengan los administradores de sitios, ayudándoles a usar tu plugin. Algo que tenía todo el sentido para ti puede ser poco 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 funciones, y tendrás que decidir si añadirlas o no.
Por último, Discourse en sí mismo está en constante desarrollo. Aunque tu plugin pueda funcionar perfectamente hoy, mañana algo podría cambiar y dejar de funcionar. Asegúrate de mantenerte al día con el desarrollo de Discourse para que puedas actualizar tu plugin y 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: Enclaves de plugins (Plugin Outlets)
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.
