Agradecemos por contribuir com a documentação do Bazel. Isso serve como um guia rápido de estilo de documentação para você começar. Para qualquer pergunta de estilo não respondida por este guia, siga o guia de estilo da documentação para desenvolvedores do Google.
Definição de princípios
Os documentos do Bazel precisam seguir estes princípios:
- concisa; Use o menor número possível de palavras.
- Limpar. Use uma linguagem simples. Escreva sem jargão para ter um nível de leitura de quinto nível.
- Consistentes. Use as mesmas palavras ou frases para conceitos repetidos em todos os documentos.
- Correto. Escreva de forma que o conteúdo permaneça correto pelo maior tempo possível, evitando informações baseadas em tempo e promessas para o futuro.
Gravação
Esta seção contém dicas básicas sobre redação.
Títulos
- Os títulos no nível da página começam no segundo semestre. Os títulos H1 são usados como títulos de página.
Crie cabeçalhos curtos. Dessa forma, eles se encaixam no TOC sem wrapper.
- Sim: permissões
- Não: uma breve observação sobre as permissões
Use letras maiúsculas para títulos
- Sim: configurar seu espaço de trabalho
- Não: configurar seu espaço de trabalho
Tente fazer com que os cabeçalhos sejam baseados em tarefas ou em ações. Se os títulos forem conceituais, pode ser baseado na compreensão, mas escreva sobre o que o usuário faz.
- Sim: preservar a ordem dos gráficos
- Não: na preservação da ordem do gráfico
Nomes
Use letras maiúsculas em nomes próprios, como Bazel e Starlark.
- Sim: no final do build, o Bazel imprime os destinos solicitados.
- Não: no final do build, o Bazel exibe os destinos solicitados.
Mantenha a consistência. Não introduzir novos nomes para os conceitos existentes. Quando aplicável, use o termo definido no Glossário.
- Por exemplo, se você estiver escrevendo sobre a emissão de comandos em um terminal, não use o terminal e a linha de comando na página.
Escopo da página
Cada página precisa ter uma finalidade e ser definida no início. Isso ajuda os leitores a encontrar o que precisam com mais rapidez.
- Sim: esta página explica como instalar o Bazel no Windows.
- Não: (sem frase introdutória)
No final da página, diga ao leitor o que fazer em seguida. Para páginas em que não há uma ação clara, é possível incluir links para conceitos, exemplos ou outras vias para exploração.
Subject
Na documentação do Bazel, o público-alvo é composto principalmente de usuários: as pessoas que usam o Bazel para criar o software.
Defina o leitor como "você". Se por algum motivo não for possível usar "você", use uma linguagem neutra de gênero, como essas.
- Sim: para criar código Java usando o Bazel, você precisa instalar um JDK.
- MAYBE: para que os usuários criem código Java com o Bazel, eles precisam instalar um JDK.
- Não: para que um usuário crie código Java com o Bazel, ele precisa instalar um JDK.
Se o público-alvo NÃO for um usuário geral do Bazel, defina-o no início da página ou na seção. Outros públicos-alvo podem incluir mantenedores, colaboradores, migrantes ou outros papéis.
Evite "nós". Nos documentos do usuário, não há um autor. Basta dizer às pessoas o que é possível.
- Sim: conforme o Bazel evolui, você precisa atualizar sua base de código para manter a compatibilidade.
- Não: o Bazel está evoluindo, e vamos fazer alterações que, às vezes, serão incompatíveis e exigirão algumas alterações dos usuários do Bazel.
Temporal
Sempre que possível, evite termos que orientam o tempo, como fazer referência a datas específicas (segundo trimestre de 2022) ou dizer "agora", "atualmente" ou "em breve". Elas ficam desatualizados rapidamente e podem estar incorretas se for uma projeção futura. Em vez disso, especifique um nível de versão, como "Bazel X.x e mais recentes oferecem suporte a <feature> ou um link de problema do GitHub.
- Sim: o Bazel 0.10.0 ou posterior é compatível com o armazenamento em cache remoto.
- Não: o Bazel vai oferecer suporte a armazenamento em cache remoto, provavelmente em outubro de 2017.
Tense
Use o tempo presente. Evite tempos passados ou futuros, a menos que seja absolutamente necessário para maior clareza.
- Sim: o Bazel emite um erro ao encontrar dependências que não estão em conformidade com essa regra.
- Não: se o Bazel encontrar uma dependência que não esteja em conformidade com essa regra, ele emitirá um erro.
Sempre que possível, use voz ativa, ou seja, um objeto que aja com base em um objeto, e não voz passiva, em que um objeto é interpretado por um sujeito. Geralmente, a voz ativa deixa as frases mais claras porque mostra quem é responsável. Se a voz ativa diminuir a clareza, use a voz passiva.
- Sim: o Bazel inicia o X e usa a saída para criar Y.
- Não: o X é iniciado pelo Bazel e, depois, Y será criado com a saída.
Tom
Escreva com um tom adequado para empresas.
Evite usar expressões coloquiais. É mais difícil traduzir frases que são específicas para o inglês.
- Sim: bons conjuntos de regras
- Não: o que é um bom conjunto de regras?
Evite linguagem excessivamente formal. Escreva como se você estivesse explicando o conceito para alguém que está curioso sobre tecnologia, mas não sabe os detalhes.
Formatação
Tipo de arquivo
Para facilitar a leitura, coloque linhas com 80 caracteres. Links longos ou snippets de código podem ser mais longos, mas devem começar com uma nova linha. Exemplo:
Links
Use um texto de link descritivo em vez de "aqui" ou "abaixo". Essa prática facilita a digitalização de um documento e é melhor para leitores de tela.
- Sim: veja mais detalhes em [Como instalar o Bazel].
- Não: veja mais detalhes [aqui].
Termine a frase com o link, se possível.
- Sim: para ver mais detalhes, consulte [link].
- Não: consulte [link] para ver mais informações.
Listas
- Use uma lista ordenada para descrever como realizar uma tarefa com etapas
- Use uma lista não ordenada para listar itens não baseados em tarefas. Ainda vai haver uma ordem, como alfabética, importância etc.,
- Escreva com uma estrutura paralela. Exemplo:
- Inclua todas as frases dos itens na lista.
- Comece com verbos que tenham o mesmo tempo.
- Use uma lista ordenada se houver etapas a serem seguidas.
Marcadores de posição
Use sinais de "menor que" e "maior que" para indicar uma variável que os usuários precisam mudar. Em Markdown, use colchetes de barra para evitar o uso dos sinais de maior e menor:
\<example\>
.- Sim:
bazel help <command>
: imprime ajuda e opções para<command>
- Não: ajuda do bazel command: imprime ajuda e opções para "comando"
- Sim:
Especialmente para amostras de código complicadas, use marcadores que façam sentido no contexto.
Índice
Use o TOC gerado automaticamente que é compatível com o site. Não adicione um TOC manual.
Código
Amostras de código são as melhores amizades dos desenvolvedores. Você provavelmente já sabe como escrever, mas estas são algumas dicas.
Se estiver fazendo referência a um pequeno snippet de código, você pode incorporá-lo em uma frase. Se você quiser que o leitor use o código, por exemplo, copiando um comando, use um bloco de código.
Blocos de código
- Seja breve. Elimine todo o texto redundante ou desnecessário de uma amostra de código.
- No Markdown, especifique o tipo de bloco de código adicionando a linguagem do exemplo.
```shell
...
- Separe os comandos e os resultados em blocos de código diferentes.
Formatação do código inline
- Use o estilo de código para nomes de arquivo, diretórios, caminhos e pequenos trechos de código.
- Use o estilo de código in-line em vez de itálico, "aspas" ou negrito.
- Sim:
bazel help <command>
: imprime ajuda e opções para<command>
- Não: ajuda do bazel command: imprime ajuda e opções para "comando"
- Sim: