Tutorial anterior: Developing Discourse Plugins - Part 6 - Add acceptance tests
Você criou seu plugin, o enviou para o GitHub e adicionou testes. Ótimo! O problema é que ninguém mais sabe dele.
Documentando seu plugin
Todos os plugins exigem boa documentação. Os usuários precisam saber o que o plugin faz, como instalá-lo, configurações/alterações importantes 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 Customization > Plugin.
Documentação no 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 com documentação mínima: 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 < > com os detalhes específicos do seu plugin.
## <Título do Plugin>
<Descrição do Plugin>
## Instalação
Siga o [guia de instalação de plugins](https://meta.discourse.org/t/install-a-plugin/19157).
## Como usar
<Explique como habilitar o plugin, as etapas de configuração necessárias e como usá-lo>
## Capturas de tela
<Inclua capturas de tela se necessário para demonstrar o uso do seu plugin>
## Leia mais
<Inclua um link para o seu tópico Meta se mais informações forem detalhadas lá>
## Licença
<Indique a licença do seu código, a maioria dos plugins do Discourse usa MIT>
Documentação no Meta
Enquanto a documentação no GitHub tende a ser curta e “direta ao ponto”, a documentação no Meta é onde você pode compartilhar todos os detalhes do seu plugin e convencer os usuários de por que eles devem usá-lo. No mínimo, seu tópico 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 com 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. As capturas de tela são fundamentais, pois os usuários querem ver o que seu plugin faz, não apenas ler sobre ele. 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 alterações maiores deve ter várias.
A documentação no Meta tende a ser mais pessoal do que no GitHub; cada autor de plugin tem seu próprio estilo de documentação. Independentemente do estilo que você escolher, certifique-se de que seja claro, fácil de ler e organizado. Use cabeçalhos conforme apropriado, anote as capturas de tela para explicar interações complexas e certifique-se de ser consistente na 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 algum tempo para documentá-lo.
Respondeu à mesma pergunta várias vezes? Considere adicionar uma seção de FAQ ao seu tópico Meta.
Problema conhecido que é complicado de corrigir? Detalhe-o em seu tópico para que os usuários saibam o que esperar.
Suportando seu plugin
Depois de publicar seu plugin e sua documentação, administradores de sites que o acharem útil podem instalá-lo em seus sites e começar a usá-lo. Esse uso exige suporte contínuo por parte do desenvolvedor do plugin. Você desejará responder às perguntas dos administradores de sites, ajudando-os a usar seu plugin. Algo que fazia todo o sentido para você pode estar 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, que você terá que decidir se deve ou não adicionar.
Por fim, 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 dar suporte à versão mais recente do Discourse quando uma alteração afetar seu plugin.
Mais na série
Parte 1: Conceitos básicos de plugins
Parte 2: Plugin Outlets
Parte 3: Configurações do site
Parte 4: Configuração do git
Parte 5: Interfaces de administração
Parte 6: Testes de aceitação
Parte 7: Este tópico
Este documento é controlado por versão - sugira alterações no github.
