A documentação do Discourse está sendo revisada e editada para alinhar-se a este guia de estilo. Nem todos os tópicos da documentação atual correspondem a isso — estamos trabalhando nisso o mais rápido possível.
Este é considerado um documento vivo que orienta como a documentação do Discourse é escrita e formatada. Este tópico será mantido atualizado conforme necessário. Se você tiver dúvidas sobre algum dos princípios aqui, poste no tópico para discutir os detalhes.
O princípio orientador por trás deste guia de estilo de documentação é considerar seus leitores e suas necessidades ao escrever a documentação: o que eles querem realizar? Qual é o seu objetivo ao fornecer o conteúdo?
Lista de verificação rápida ao implementar o guia de estilo:
- O bloco de metadados está presente e correto
- O título é orientado a ação
- Todos os títulos usam minúsculas para frases
- Tags e categorias corretas são usadas
- O documento está estruturado logicamente
Ao concluir um documento, revise-o para garantir que todos esses critérios sejam atendidos.
Por favor, observe estas diretrizes de formatação de texto:
Informações de metadados
- O documento deve pertencer a uma e apenas uma das seguintes categorias:
- Usando o Discourse
- Guias gerais para usuários em tarefas não administrativas
- Gerenciamento do site
- Configurações, plugins, conteúdo e administração geral do site
- Integrações
- Guias para integrar outras plataformas com o Discourse
- Clientes hospedados
- Guias relevantes apenas para clientes hospedados
- Auto-hospedagem
- Guias relevantes apenas para sites auto-hospedados
- Guias para desenvolvedores
- Guias técnicos para desenvolver sobre o Discourse, incluindo criação de temas, componentes de temas e plugins
- Contribuindo
- Guias para contribuir com o projeto de código aberto do Discourse
- Usando o Discourse
- O documento deve pertencer a uma e apenas uma das seguintes tags / tipos de documento:
#how-to#explanation#reference#tutorial
- O documento pode ter outras tags aplicáveis, com um máximo absoluto de 5 tags em um único documento
Bloco de metadados
Todos os documentos devem ter um bloco no topo que inclua uma breve explicação sobre o que o documento trata, além de quaisquer outras informações de metadados relevantes, como requisitos de nível de usuário, se é necessário acesso ao console ou qualquer outra coisa. Isso será formatado em um bloco de citação sem um título sobre ele. Aqui está um exemplo do que isso deve parecer:
Este é um guia para descrever todas as configurações ocultas do site disponíveis, como ativá-las e por que você pode querer ajustá-las.
Nível de usuário necessário: Administrador
Acesso ao console necessário
Títulos e cabeçalhos
- Faça os títulos do documento orientados a ação
- Incorreto: “Como ativar títulos automáticos para threads de chat”
- Correto: “Ativando títulos automáticos para threads de chat”
- Os títulos dos documentos não devem ser muito longos
- Para tópicos ‘how-to’, faça o título orientado ao objetivo
- Todos os títulos devem ser específicos e únicos
- Não use pontuação ou caracteres especiais em títulos de documentos, exceto vírgulas
- Não inclua emojis em títulos de documentos
- Use minúsculas para frases em títulos e cabeçalhos — isso significa que apenas a primeira palavra começa com letra maiúscula, junto com nomes próprios e quaisquer outras palavras que normalmente seriam capitalizadas
- Não use símbolos de e comercial (&) em cabeçalhos; use a palavra completa (“e”)
Diretrizes gerais de escrita, tom e gramática
- Use a voz segunda pessoa ao se referir às pessoas que leem o documento — ou seja, use “você”, não “nós”
- Use a voz ativa o máximo possível
- Incorreto: “o botão deve ser clicado”
- Correto: “clique no botão”
- Defina siglas e abreviações quando usadas pela primeira vez; se necessário, forneça um link externo que ofereça mais informações
- Use frases curtas e divida o texto usando parágrafos, cabeçalhos e listas mais curtos
- Você pode usar
**negrito**e itálico para enfatizar frases ou palavras-chave, mas não exagere - Evite usar jargão ou termos técnicos sem explicações — em caso de dúvida, inclua a explicação
- Use capturas de tela ao descrever uma interface visual, como um elemento de UI
- Não documente nem tente divulgar recursos, produtos ou serviços futuros do Discourse, a menos que explicitamente permitido
- Use palavras de transição, como portanto, embora e além disso.
- Use contrações comuns: está, você vai, você está, nós estamos, vamos
- Infira atemporalidade na documentação — evite palavras como em breve, novo, agora, mais recente, etc., que rapidamente se tornam irrelevantes
- Não atribua qualidades humanas a software ou hardware
- Ex.: “Se você passar um inteiro para esta API, ela ficará brava e lançará um erro”
- Ex.: “Nosso amigável e ambicioso bot de IA ajudará a resolver todos os seus problemas”
- Ao citar texto (incluindo da interface do Discourse), use “aspas”
- Ao citar uma URL, use
backticks - Ao usar um domínio de exemplo, use
discourse.exemplo.com - Se for útil, você pode usar emojis no início de um parágrafo para destacá-lo. Não use mais de dois ou três desses em um único tópico. Alguns emojis de exemplo que você pode usar:
- - Uma nota informativa
- Anúncio ou aviso
- Uma mensagem de aviso
- Informação muito importante
- Evite:
- Metáforas ou humor desnecessários
- Referências culturais e regionais
- Dictar ou ordenar procedimentos em um tom condescendente — ex.: Você deve clicar em Publicar ou Você precisa clicar em Publicar
- Ser excessivamente educado. Por exemplo, Por favor, clique em Publicar
- Usar pontos de exclamação, a menos que absolutamente necessário
- Capitalizar palavras onde não é necessário
- Uso excessivo das mesmas frases e pronomes
Para documentação de usuário final:
Mantenha um tom amigável e informal, com foco em ser claro e conciso de maneira conhecedora. Vá direto ao ponto. Explique termos técnicos, mas cuidado para não ser condescendente. Para garantir clareza, comece especificando brevemente o contexto do tópico atual.
Para documentação de desenvolvedor e técnica:
Mantenha um tom direto e preciso. Use o mesmo tom que você usaria para documentação de usuário, mas pode assumir um nível mais alto de conhecimento técnico em seus leitores.
Estrutura
- Vá direto ao ponto — comece com o que é mais importante
- Inclua palavras-chave importantes cedo no documento
- Torne as escolhas do leitor e os próximos passos óbvios
- Sempre use marcação leve para escrever documentação (Isso já está integrado ao Discourse com Markdown-it).
- Referência de uso: https://markdown-it.github.io/
- Organize sua documentação em um fluxo lógico — comece com uma visão geral, seguida por seções detalhadas e um resumo ou conclusão, se aplicável
- Use cabeçalhos e subcabeçalhos para estruturar seu conteúdo, facilitando a leitura e a localização de informações específicas — use hierarquia decrescente em cabeçalhos, começando com h2, e não pule níveis
- Forneça links para tópicos ou seções relacionados dentro da sua documentação — isso ajuda os usuários a encontrar informações adicionais sem buscas desnecessárias
Links
- Use texto significativo em links
- A menos que o formato da URL seja importante ou instrutivo, não use uma URL como texto do link — em vez disso, use o título da página ou uma descrição da página
- Link para sites e fontes externos em vez de citar ou reescrever documentação existente
- Garanta que os sites aos quais você linka sejam de alto padrão e qualidade
- Se o link baixar um arquivo, mencione explicitamente isso — também indique o tipo de arquivo sendo baixado e uma estimativa aproximada do tamanho do arquivo
Código na documentação
- Use blocos de código com destaque de sintaxe específico da linguagem quando possível para exemplos grandes de código
- Se não for autoexplicativo, introduza um exemplo de código com uma frase introdutória que inicie o exemplo que segue — em caso de dúvida, inclua a explicação
- Exemplos de código devem seguir as melhores práticas para escrever código na linguagem de programação relevante
- Use código inline para expressar atributos básicos de código ou quando um bloco de código completo não for necessário, como:
- Nomes e valores de atributos
- Nomes de classes
- Nomes de utilitários de linha de comando
- Tipos de dados
- Nomes de variáveis de ambiente
- Nomes de arquivos, extensões de arquivo e caminhos
- Pastas e diretórios
- Verbos HTTP, códigos de status e valores de tipo de conteúdo
- Nomes e valores de parâmetros de consulta
- Entrada de texto
- Quando você usar um placeholder em exemplos de código, comandos ou outro texto, inclua uma explicação do que o placeholder representa
- Escreva uma explicação na primeira vez que usar o placeholder; se houver múltiplos placeholders ou etapas após a primeira utilização desse placeholder, você pode explicar o placeholder novamente
- Forneça uma maneira fácil para usuários ou desenvolvedores copiarem e executarem o código.
- Mostre a saída esperada, seja em uma seção separada após o exemplo de código ou usando comentários de código dentro do exemplo de código
- Escreva código seguro — nunca codifique senhas, chaves de API ou informações seguras no código
Procedimentos e guias passo a passo
- Formate procedimentos consistentemente, para que os leitores possam encontrá-los facilmente ao analisar
- Use uma entrada numerada separada para cada etapa
- Inclua ações que finalizam uma etapa, como botões OK ou Aplicar
- Se a instrução aparecer na mesma interface onde a ação ocorre, geralmente não é necessário fornecer detalhes de localização
- Se você precisar garantir que o leitor comece no lugar certo, forneça uma breve frase no início da etapa
Acessibilidade e inclusão
- Use capturas de tela, diagramas ou vídeos onde agreguem valor, especialmente para explicar etapas complexas ou mostrar partes de uma interface
- Imagens devem ser usadas para apoiar informações textuais, não substituí-las
- Sempre use atributos
altpara imagens - Sempre forneça legendas ou transcrições para vídeos
- Use GIFs apenas se você puder explicar completamente o conteúdo em texto
- Escolha imagens simples e recorte detalhes desnecessários
- Use linguagem simples e evite figuras de linguagem ou expressões idiomáticas que possam não ser universalmente compreendidas
- Considere que seu documento será usado em uma multitude de dispositivos
- Use linguagem neutra em termos de gênero. Não use ele, ele, dele, ela, dela, dela ao se referir a pessoas — para escrever sem pronomes, você pode:
- Reescrever usando a segunda pessoa (você)
- Reescrever a frase para ter um substantivo plural e pronome
- Usar as palavras pessoa ou indivíduo
- Usar artigos o, um ou uma em vez de um pronome
- Usar um pronome plural, como eles, deles ou a eles, mesmo que se refira a um único indivíduo
- Quando estiver escrevendo sobre uma pessoa real, use os pronomes que essa pessoa prefere
- Seja inclusivo em relação à identidade de gênero, raça, cultura, religião, capacidade, idade, orientação sexual e classe socioeconômica — inclua uma ampla variedade de profissões, culturas, contextos educacionais, locais e configurações econômicas em exemplos
- Evite conteúdo politizado — em casos onde conteúdo político precisa ser incluído, mantenha-se neutro
- Não faça generalizações sobre pessoas, países e culturas, nem mesmo generalizações positivas ou neutras
- Não escreva conteúdo preconceituoso e discriminatório contra qualquer comunidade, especialmente minorias
- Evite termos qualitativos relacionados a eventos históricos
- Evite usar termos e metáforas associados à violência e ações militares
.
). Bom ponto sobre a inconsistência. Não tenho certeza de qual escolheremos, mas definitivamente garantiremos que escolheremos um e o manteremos. 