Guia de estilo de documentos do Bazel

Nightly · 9.0 · 8.6 · 8.5 · 8.4 · 8.3 · 8.2 · 7.7

Agradecemos sua contribuição para a documentação do Bazel. Este é um guia de estilo de documentação rápido para você começar. Para perguntas sobre estilo que não forem respondidas neste 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:

  • Conciso. Use o mínimo de palavras possível.
  • Claro. Use linguagem simples. Escreva sem jargões para um nível de leitura do quinto ano do ensino fundamental.
  • Consistente. 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 no tempo e promessas para o futuro.

Escrita

Esta seção contém dicas básicas de escrita.

Títulos

  • Os títulos no nível da página começam em H2. (Os títulos H1 são usados como títulos de página.)

  • Deixe os cabeçalhos o mais curtos possível. Dessa forma, eles se encaixam no índice sem quebra de linha.

    • Sim: Permissões
    • Não: Uma breve observação sobre permissões

  • Use letras maiúsculas apenas na primeira palavra para títulos

    • Sim: Configure seu espaço de trabalho
    • Não: Configure seu espaço de trabalho

  • Tente criar títulos baseados em tarefas ou acionáveis. Se os títulos forem conceituais, eles poderão ser baseados na compreensão, mas escreva sobre o que o usuário faz.

    • Sim: Preservar a ordem do gráfico
    • Não: Sobre a preservação da ordem do gráfico

Nomes

  • Use letras maiúsculas em substantivos 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 imprime os destinos solicitados.

  • Mantenha esse tipo consistente. Não introduza novos nomes para conceitos atuais. Quando aplicável, use o termo definido no glossário.

    • Por exemplo, se você estiver escrevendo sobre como emitir comandos em um terminal, não use "terminal" e "linha de comando" na página.

Escopo da página

  • Cada página precisa ter uma finalidade, que deve ser definida no início. Isso ajuda os leitores a encontrar o que precisam mais rapidamente.

    • Sim: Esta página aborda 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, você pode incluir links para conceitos semelhantes, exemplos ou outras formas de exploração.

Assunto

Na documentação do Bazel, o público-alvo precisa ser principalmente de usuários, ou seja, pessoas que usam o Bazel para criar softwares.

  • Dirija-se ao leitor como "você". Se, por algum motivo, você não puder usar "você", use uma linguagem neutra em termos de gênero, como "eles".

    • Sim: Para criar código Java usando o Bazel, você precisa instalar um JDK.
    • TALVEZ: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 de usuários gerais do Bazel, defina-o no início da página ou na seção. Outros públicos podem incluir mantenedores, colaboradores, migradores ou outras funções.

  • Evite usar "nós". Nos documentos do usuário, não há autor. Basta dizer às pessoas o que é possível.

    • Sim: À medida que o Bazel evolui, você precisa atualizar sua base de código para manter a compatibilidade.
    • Não: O Bazel está evoluindo, e vamos fazer mudanças que, às vezes, serão incompatíveis e exigirão algumas mudanças dos usuários do Bazel.

Temporal

Sempre que possível, evite termos que orientam as coisas no tempo, como referências a datas específicas (segundo trimestre de 2022) ou dizer "agora", "atualmente" ou "em breve". Esses termos ficam desatualizados rapidamente e podem estar incorretos se forem uma projeção futura. Em vez disso, especifique um nível de versão, como "O Bazel X.x e versões mais recentes são compatíveis com <recurso> ou um link de problema do GitHub.

  • Sim: O Bazel 0.10.0 ou versões mais recentes são compatíveis com o armazenamento em cache remoto.
  • Não: O Bazel vai oferecer suporte ao armazenamento em cache remoto em breve, provavelmente em outubro de 2017.

Tense

  • Use o tempo presente. Evite o tempo passado ou futuro, a menos que seja absolutamente necessário para clareza.

    • Sim: O Bazel emite um erro quando ele encontra 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 vai emitir um erro.

  • Sempre que possível, use a voz ativa (em que um sujeito age sobre um objeto) e não a voz passiva (em que um objeto é agido por um sujeito). Geralmente, a voz ativa torna as frases mais claras porque mostra quem é o responsável. Se o uso da voz ativa prejudicar a clareza, use a voz passiva.

    • Sim: O Bazel inicia X e usa a saída para criar Y.
    • Não: X é iniciado pelo Bazel e, em seguida, Y será criado com a saída.

Tom

Escreva com um tom adequado para empresas.

  • Evite linguagem coloquial. É mais difícil traduzir frases que são específicas do inglês.

    • Sim: Bons conjuntos de regras
    • Não: O que é um bom conjunto de regras?

  • Evite linguagem excessivamente formal. Escreva como se estivesse explicando o conceito para alguém que tem curiosidade sobre tecnologia, mas não conhece os detalhes.

Formatação

Tipo de arquivo

Para facilitar a leitura, quebre as linhas em 80 caracteres. Links longos ou snippets de código podem ser mais longos, mas precisam começar em uma nova linha. Exemplo:

  • Use texto de link descritivo em vez de "aqui" ou "abaixo". Essa prática facilita a leitura de um documento e é melhor para leitores de tela.

    • Sim: Para mais detalhes, consulte [Instalar o Bazel].
    • Não: Para mais detalhes, consulte [aqui].

  • Termine a frase com o link, se possível.

    • Sim: Para mais detalhes, consulte [link].
    • Não: Consulte [link] para mais informações.

Listas

  • Use uma lista ordenada para descrever como realizar uma tarefa com etapas
  • Use uma lista não ordenada para listar coisas que não são baseadas em tarefas. Ainda precisa haver uma ordem , como alfabética, importância etc.
  • Escreva com estrutura paralela. Por exemplo:
    1. Crie frases para todos os itens da 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 colchetes angulares para denotar uma variável que os usuários precisam mudar. No Markdown, faça o escape dos colchetes angulares com uma barra invertida: \<example\>.

    • Sim: bazel help <command>: Imprime a ajuda e as opções de <command>
    • Não: bazel help command: imprime a ajuda e as opções de "command"

  • Especialmente para exemplos de código complicados, use marcadores de posição que façam sentido no contexto.

Índice

Use o índice gerado automaticamente com suporte do site. Não adicione um índice manual.

Código

Exemplos de código são ótimos para desenvolvedores. Você provavelmente já sabe como escrever esses exemplos, mas aqui estão algumas dicas.

Se você estiver fazendo referência a um pequeno snippet de código, poderá incorporá-lo em uma frase. Se você quiser que o leitor use o código, como copiar um comando, use um bloco de código.

Blocos de código

  • Seja breve. Elimine todo o texto redundante ou desnecessário de um exemplo de código.
  • No Markdown, especifique o tipo de bloco de código adicionando a linguagem do exemplo.
```shell
...
  • Separe comandos e saída em blocos de código diferentes.

Formatação de código inline

  • Use o estilo de código para nomes de arquivos, diretórios, caminhos e pequenos bits de código.
  • Use o estilo de código inline em vez de itálico, "aspas" ou negrito.
    • Sim: bazel help <command>: Imprime a ajuda e as opções de <command>
    • Não: bazel help command: imprime a ajuda e as opções de "command"