Guia de estilo de documentos do Bazel

7.3 · 7.2 · 7.1 · 7.0 · 6.5

Agradecemos por contribuir com a documentação do Bazel. Este é um guia rápido de estilo de documentação para você começar. Para dúvidas de estilo não 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:

  • Concise. Use o menor número possível de palavras.
  • Limpar. Use uma linguagem simples. Escreva sem jargões para um nível de leitura do 5º ano.
  • Consistentes. Use as mesmas palavras ou frases para conceitos repetidos em todos os documentos.
  • Correto. Escreva de uma maneira que o conteúdo permaneça correto pelo maior tempo possível, evitando informações baseadas em tempo e promessas para o futuro.

Escrita

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

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.

  • Faça com que os cabeçalhos sejam o mais curtos possível. Dessa forma, eles se encaixam no TOC sem quebras.

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

  • Use letra maiúscula apenas na primeira palavra dos títulos

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

  • Tente fazer com que os títulos sejam baseados em tarefas ou acionáveis. Se os títulos forem conceituais, eles podem ser baseados na compreensão, mas escritos para 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 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 a consistência. Não introduza novos nomes para conceitos existentes. 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 o terminal e a linha de comando na página.

Escopo da página

  • Cada página precisa ter uma finalidade e ela precisa 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: nenhuma frase introdutória.

  • No final da página, diga ao leitor o que fazer a seguir. Para páginas em que não há uma ação clara, é possível incluir links para conceitos, exemplos ou outros caminhos semelhantes para análise.

Assunto

Na documentação do Bazel, o público-alvo deve ser principalmente os usuários, as pessoas que usam o Bazel para criar softwares.

  • Fale com o leitor como "você". Se por algum motivo você não puder usar "você", use linguagem neutra em termos de gênero, como "eles".

    • Sim: para criar código Java usando o Bazel, é necessário instalar um JDK.
    • TAlvez: para que os usuários possam criar 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 geral, defina-o no início da página ou na seção. Outros públicos-alvo podem incluir mantenedores, colaboradores, migradores ou outras funções.

  • Evite usar "nós". Nos documentos do usuário, não há um autor. Apenas informe à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 nele que, às vezes, serão incompatíveis e exigirão algumas mudanças dos usuários.

Temporal

Sempre que possível, evite termos que orientem as coisas no tempo, como a referência a datas específicas (2º trimestre de 2022) ou a palavras "agora", "atualmente" ou "em breve". Elas ficam desatualizadas 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 versões mais recentes oferecem suporte a <feature> ou um link para o problema do GitHub.

  • Sim: o Bazel 0.10.0 ou mais recente oferece suporte ao armazenamento em cache remoto.
  • Não: o Bazel vai oferecer suporte à criação de 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 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, emitirá um erro.

  • Sempre que possível, use voz ativa, em que a pessoa age sobre um objeto, e não a voz passiva, quando o objeto é interagido. Em geral, a voz ativa deixa as frases mais claras porque mostra quem é o responsável. Se usar a voz ativa prejudicar a clareza, use a voz passiva.

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

Tom

Escreva com um tom comercial.

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

    • Sim: boas regras
    • Não: o que é uma boa regra?

  • Evite usar uma linguagem muito 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 descritivo no link 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 [este link].

  • Se possível, termine a frase com o link.

    • 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 deve haver uma ordem de classificação, como alfabética, importância etc.)
  • Escrever com estrutura paralela. Exemplo:
    1. Crie frases para todos os itens da lista.
    2. Comece com verbos que estão no mesmo tempo.
    3. Use uma lista ordenada se houver etapas a seguir.

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>: mostra ajuda e opções para <command>
    • Não: bazel help command: imprime ajuda e opções para "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 compatível com o site. Não adicione um índice manual.

Código

Os exemplos de código são os melhores amigos dos desenvolvedores. Você provavelmente já sabe como escrever essas informações, 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ídas em diferentes blocos de código.

Formatação de código inline

  • Use um estilo de código para nomes de arquivos, diretórios, caminhos e pequenos trechos de código.
  • Use o estilo de código inline em vez de itálico, aspas ou bolding.
    • Sim: bazel help <command>: mostra ajuda e opções para <command>
    • Não: bazel help command: exibe ajuda e opções para "command".