Escrevendo Prosa
Estas regras se aplicam à documentação em markdown e aos comentários de código (doc comments), em qualquer linguagem. Regras marcadas como "apenas markdown" não se aplicam a comentários de código. Nessas áreas, comentários de código seguem as convenções de sua linguagem, como os links de documentação [Nome] do Go. Skills para tipos específicos de documento, como ADRs e glossários, adicionam suas próprias regras sobre estas.
Tom
Relaxado, mas preciso. Escreva como um engenheiro experiente explicando o tópico para outro engenheiro. Evite linguagem de especificação excessivamente formal. Prefira explicações claras e naturais que permaneçam tecnicamente precisas. O tom deve ser acessível e coloquial, mas não casual.
Suponha que os leitores tenham um entendimento intermediário de desenvolvimento de software, mas podem não conhecer projetos Dogmatiq ou o domínio do documento. Evite jargões e explique qualquer termo técnico que o documento exigir. Imagine o leitor como um desenvolvedor de aplicativos com cerca de cinco anos de experiência profissional, que conhece Go, mas tem pouca formação em algoritmos ou matemática.
Nomes de arquivos (apenas markdown)
Use nomes de arquivo em letras minúsculas, como glossary.md, a menos que uma convenção externa exija o contrário, como LICENSE ou README.md.
Quebra de linha (apenas markdown)
Reformate cada parágrafo para que cada linha caiba o máximo de palavras possível dentro de 80 caracteres.
Pontuação
- Use aspas e apóstrofos retos (
",') na prosa, nunca curvos. Caracteres não ASCII são aceitáveis em blocos de código e fórmulas. - Escreva travessões com um espaço de cada lado, como em
palavra — palavra. - Use um travessão, não hífens, como separador parentético.
- Use um travessão para uma aposição que define um termo, em listas e parágrafos. Não use dois pontos, ponto e vírgula ou parênteses para isso.
- Considere reestruturar frases ou parágrafos que contenham muitos travessões.
- Use ponto e vírgula com moderação, para contraste (A; B não faz), qualificação (A; no entanto B) ou consequência lógica (A; portanto B). Prefira um ponto final se as orações fluírem naturalmente como duas frases separadas.
- Substitua um hífen duplo (
--) na prosa por um travessão quando apropriado. Caso contrário, sugira a pontuação correta.
Ortografia
Use inglês americano. Em caso de dúvida, siga go.dev, a documentação da biblioteca padrão Go, ou a documentação da AWS e GCP.
| EUA (correto) | Não EUA (incorreto) |
|---|---|
| analyze | analyse |
| behavior | behaviour |
| canceled | cancelled |
| center | centre |
| color | colour |
| initialize | initialise |
| labeled | labelled |
| serialize | serialise |
Links de referência (apenas markdown)
- Use links no estilo de referência, nunca links inline.
- Coloque as definições de link no final do arquivo, em grupos que cada um comece com um comentário HTML de rotulagem, como
<!-- references -->ou<!-- anchors -->. - Ordene cada grupo alfabeticamente por rótulo. A exceção são os links de versão em um
CHANGELOG.md, que permanecem em ordem crescente de versão, então[0.9.0]vem antes de[0.10.0]. - Quando um termo vinculado aparecer no plural, adicione uma definição separada para o plural, como
[instructions]: #instruction, para que a fonte leia naturalmente. - Cada definição deve ser usada pelo menos uma vez. Remova definições não utilizadas.
- Cada referência deve ter uma definição correspondente. Não deixe referências quebradas.
Revisando
Verifique o texto contra cada regra acima. Para cada problema, cite o texto, nomeie a regra que ele quebra e sugira uma correção.