Este guia fornece instruções sobre como escrever documentação eficaz do tipo “como fazer” para o Discourse. Ele abrange elementos essenciais, como estrutura e estilo, consideração do público-alvo e manutenção.
Nível de usuário necessário: Qualquer pessoa pode escrever novos guias de “como fazer”
Escrever documentação eficaz do tipo “como fazer” é crucial para ajudar usuários, moderadores, administradores e administradores de sistema a realizar várias tarefas no Discourse. Este guia ajudará você a criar guias claros e valiosos para a comunidade.
Resumo
Nesta documentação, você aprenderá:
- Por que escrever um guia de “como fazer” é importante
- Quais informações devem ser incluídas
- Diretrizes para estrutura e estilo
- Onde publicar esses tópicos
- Como mantê-los atualizados após a publicação
Por que escrever um guia de “como fazer”?
Você já precisou realizar uma tarefa e não conseguia lembrar como fazê-la? Escrever um documento do tipo “como fazer” é uma excelente maneira de documentar processos no Discourse. Se você está com dificuldades em um processo específico, é provável que outras pessoas também estejam. Documentá-lo ajuda a todos.
Saiba mais sobre o que diferencia um guia de “como fazer” de outros tipos de documentação, como tutoriais ou guias de referência, neste guia do Divio.
Escrever ou revisar um guia de “como fazer” é uma ótima maneira de começar a contribuir com seu conhecimento sobre o Discourse para a comunidade. Para outras formas de contribuir, consulte o guia sobre como contribuir para o Discourse.
Quais informações devem ser incluídas?
Um guia de “como fazer” deve ser um passo a passo que leve o usuário a um resultado específico. Por exemplo, um guia intitulado “Configurando HTTPS para o Discourse” deve fornecer instruções para configurar o HTTPS.
Pontos-chave a lembrar ao escrever um guia de “como fazer”:
- Mantenha-se no tópico e seja claro
- Evite informações desnecessárias
- Seja conciso, mas informativo
- Explique por que alcançar o resultado final é benéfico
Considere seu público
Existem diferentes públicos para guias de “como fazer” do Discourse, cada um exigindo um nível diferente de detalhe. Use as categorias de documentação como guia para quem você deve mirar com seu guia:
- Documentation > Using Discourse
- Documentation > Site Management
- Documentation > Integrations
- Documentation > Hosted Customers
- Documentation > Self-Hosting
- Documentation > Migrating to Discourse
- Documentation > Developer Guides
- Documentation > Contributing
Entenda o nível de habilidade técnica do seu público e adapte seu guia de acordo. Algumas dicas:
- Evite etapas que o público não possa realizar (por exemplo, clientes hospedados geralmente não têm acesso a comandos de console)
- Mantenha as instruções claras e evite linguagem altamente técnica para usuários não técnicos
- Não adicione informações de fundo que seu público já deveria conhecer
Estrutura e estilo
O guia de estilo de documentação cobre tudo o que você precisa saber sobre como estruturar e estilizar guias de “como fazer” (e toda a documentação do Discourse):
Publicando um guia
Publique guias em uma subcategoria da categoria pai Documentation e marque-os com how-to. Todos os guias precisam de aprovação da equipe do Discourse, que será processada automaticamente pelo sistema de moderação. O guia de estilo descreve cada categoria com mais detalhes para ajudá-lo a decidir onde seu guia deve ser publicado.
Mantendo seu guia
Depois de publicar um guia de “como fazer”, mantenha-o atualizado. Veja como você pode ajudar a mantê-lo:
- Acompanhe as respostas — Integre o feedback da comunidade ao guia.
- Teste o guia você mesmo — Revise o guia periodicamente para garantir que ainda esteja preciso.
- Edite informações faltantes ou incorretas — Se você estiver no Nível de Confiança 2 ou superior, edite a primeira postagem do guia de “como fazer”.
- Sinalize tópicos para assistência — Se não puder fazer uma edição, sinalize a postagem com “Outra coisa” e explique o que é necessário.
Na maioria dos casos, comentários em guias oficiais de “como fazer” serão excluídos após um mês para manter o foco no próprio guia.
Obrigado por melhorar a documentação da comunidade do Discourse! Se você estiver com dificuldades, não hesite em pedir ajuda. A melhor maneira de começar é contribuindo e aprendendo no processo.