Recentemente, temos nos esforçado para melhorar nossa documentação aqui no meta, com foco em categorizar as coisas de forma que diferentes usuários possam encontrar tópicos relevantes para eles e ignorar os que não são.
Nosso objetivo é que toda a documentação se enquadre em uma das seguintes categorias:
- #documentation:users - uso geral comum
- #documentation:moderators - moderação de uma comunidade
- #documentation:theme-developers - desenvolvimento de temas e componentes de temas
- #documentation:admins - administração de um site Discourse
- #documentation:devs - desenvolvimento de recursos, plugins e integrações do Discourse
- #documentation:sysadmin - administração de sistemas auto-hospedados
Planejamos remover #documentation:faq e #documentation:tips-and-tricks no final deste período (mas já começamos a marcar alguns tópicos nas novas categorias com #tips-and-tricks).
Também pretendemos marcar a documentação com uma destas tags de classificação emprestadas do divio, conforme esta postagem anterior:
As coisas nem sempre se encaixam perfeitamente. Em alguns casos, estamos dividindo tópicos e, em outros, estamos apenas usando a tag ou categoria que melhor se adapta ao seu estado atual.
Algumas mudanças comuns que temos feito em tópicos individuais até agora (estamos cerca de 50% concluídos agora).
- Mover itens de #documentation:admins para #documentation:sysadmin quando exigem acesso ao console.
- Dividir tópicos de #documentation:faq em tópicos para #documentation:admins e tópicos para #documentation:users.
- Mover tópicos de #documentation:devs para #documentation:theme-developers quando são específicos para o desenvolvimento de temas ou componentes de temas.
- Atualizar títulos de tópicos para serem mais consistentes
- Usar tempo imperativo para títulos de tópicos (e remover “como fazer” do título).
- Usar capitalização normal de frases
- Formatar conteúdo com cabeçalhos a partir de H2
(Relacionado: também habilitamos o Sumário para todos os tópicos de documentação)
Em alguns casos, estamos fazendo algumas alterações no conteúdo em si, mas mergulhar fundo não é nosso objetivo imediato. Em uma passagem futura, gostaríamos de fazer coisas como:
- Incorporar conteúdo de respostas na própria documentação
- Excluir todas as respostas
- Configurar tópicos para excluir respostas após 1 ou 2 meses
Em seguida, daqui para frente, forneceremos orientações atualizadas sobre como contribuir com novas documentações e manter as existentes, além de atualizar os seguintes tópicos:
Podemos querer transformar mais documentações em Wikis ou encontrar novos proprietários para documentações quando elas estão sendo mantidas por alguém que não seja o autor original, por exemplo.
Também achamos que pode haver uma oportunidade aqui para criar um espaço separado para as pessoas fazerem mais “mostrar e contar”, semelhante a parte do conteúdo que estava em #documentation:tips-and-tricks. Criar um espaço para tópicos como esses fora da documentação pode permitir mais espaço para discussões sobre eles entre colegas. Mas, semelhante ao que estamos fazendo agora com a documentação, talvez seja útil ter espaços separados para administradores de sistemas, administradores e desenvolvedores para essas discussões. O que você acha?