Tutorial anterior: Developing Discourse Plugins - Part 6 - Add acceptance tests
Você já criou seu plugin, você já o enviou para o GitHub e você já adicionou testes. Ótimo! O problema é que ninguém mais sabe sobre ele.
Documentando seu plugin
Todos os plugins exigem uma boa documentação. Os usuários precisam saber o que o plugin faz, como instalá-lo, quais configurações/alterações importantes são necessárias e como usá-lo. Os plugins devem ser documentados em dois locais diferentes: o arquivo README.md dentro do seu repositório git e um tópico dedicado na categoria Plugin.
Documentação do GitHub
O arquivo README.md no GitHub é importante, pois é exibido por padrão quando um usuário visita seu repositório. No mínimo, seu readme deve incluir o título do plugin e uma breve descrição. Um readme mais completo também incluirá instruções de instalação, uma descrição mais detalhada, instruções básicas de uso, licença e (se aplicável) capturas de tela. Se instruções adicionais estiverem incluídas no tópico Meta do seu plugin, certifique-se de incluir um link para o tópico.
Exemplo de um plugin minimamente documentado: Discourse Data Explorer
Exemplos de plugins com documentação mais completa: Discourse Solved, Discourse OAuth2 Basic e Discourse Ads.
Modelo de README de plugin de exemplo
Certifique-se de atualizar o texto cercado por \u003c\u003e com os detalhes específicos do seu plugin.
## \u003cTítulo do Plugin\u003e
\u003cDescrição do Plugin\u003e
## Instalação
Siga o [guia de instalação de plugins](https://meta.discourse.org/t/install-a-plugin/19157).
## Como usar
\u003cExplique como habilitar o plugin, as etapas de configuração necessárias e como usá-lo\u003e
## Capturas de tela
\u003cInclua capturas de tela, se necessário, para demonstrar o uso do seu plugin\u003e
## Leia Mais
\u003cInclua um link para o seu tópico Meta se mais informações forem detalhadas lá\u003e
## Licença
\u003cIndique a licença do seu código, a maioria dos plugins do Discourse usa MIT\u003e
Documentação do Meta
Onde a documentação do GitHub tende a ser curta e “direta ao ponto”, a documentação do Meta é onde você pode compartilhar todos os detalhes do seu plugin e convencer os usuários por que eles devem usá-lo. No mínimo, seu tópico do Meta deve incluir uma breve descrição do plugin e um link para o repositório do plugin no GitHub (para que os usuários possam instalá-lo). Uma documentação mais completa também incluirá uma descrição detalhada, incluindo exemplos de casos de uso, instruções de uso detalhadas, documentação de todas as configurações e opções de configuração, e capturas de tela. Capturas de tela são fundamentais, pois os usuários querem ver o que seu plugin faz, e não apenas ler sobre isso. Um plugin que adiciona um provedor de autenticação provavelmente precisa de apenas 1 captura de tela, enquanto um plugin que adiciona uma nova interface ou faz grandes alterações deve ter muitas.
A documentação do Meta tende a ser mais pessoal do que a do GitHub; cada autor de plugin tem seu próprio estilo de documentação. Qualquer estilo que você escolher, certifique-se de que seja claro, fácil de ler e organizado. Use cabeçalhos conforme apropriado, anote capturas de tela para explicar interações complexas e certifique-se de ser consistente na sua formatação. Evite a tentação de escrever um único parágrafo gigante.
Atualizando sua documentação
Depois de escrever sua documentação inicial, é importante mantê-la atualizada.
Adicionou um novo recurso ao plugin? Certifique-se de reservar um tempo para documentá-lo.
Respondeu à mesma pergunta várias vezes? Considere adicionar uma seção de FAQ ao seu tópico do Meta.
Problema conhecido que é complicado de corrigir? Detalhe-o no seu tópico para que os usuários saibam o que esperar.
Dando suporte ao seu plugin
Depois de publicar seu plugin e sua documentação, os administradores de site que o considerarem útil podem instalá-lo em seus sites e começar a usá-lo. Esse uso requer suporte contínuo por parte do desenvolvedor do plugin. Você desejará responder às perguntas que os administradores de site tiverem, ajudando-os a usar seu plugin. Algo que fez todo o sentido para você pode ser obscuro para outros, então você desejará atualizar o código e/ou a documentação para esclarecê-lo. Você pode receber solicitações de recursos, sobre as quais terá que decidir se as adicionará ou não.
Por último, o próprio Discourse está em constante desenvolvimento. Embora seu plugin possa funcionar perfeitamente hoje, amanhã algo pode mudar e quebrá-lo. Certifique-se de se manter atualizado sobre o desenvolvimento do Discourse para que você possa atualizar seu plugin para suportar a versão mais recente do Discourse quando uma alteração afetar seu plugin.
Mais na série
Parte 1: Noções Básicas de Plugin
Parte 2: Outlets de Plugin
Parte 3: Configurações do Site
Parte 4: Configuração do git
Parte 5: Interfaces de Administrador
Parte 6: Testes de Aceitação
Parte 7: Este tópico
Este documento é controlado por versão - sugira alterações no github.
