Guia de estilo de documentos do Bazel

Informar um problema Ver código-fonte

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:

  • 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:
    1. Inclua todas as frases dos itens na lista.
    2. Comece com verbos que tenham o mesmo tempo.
    3. 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"

  • 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"