Guia de estilo de documentos do Bazel

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.

Princípios de definição

Os documentos do Bazel precisam seguir estes princípios:

• Concisa. Use o mínimo de palavras possível.
• Limpar. Use uma linguagem simples. Para um nível de leitura do quinto ano, escreva sem jargões.
• Consistente. Use as mesmas palavras ou frases para conceitos repetidos ao longo dos documentos.
• Correto. Escreva de maneira que o conteúdo permaneça correto pelo maior tempo possível, evitando informações e promessas baseadas em tempo 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 cabeçalhos H1 são usados como títulos de página.)

• Use cabeçalhos curtos o mais rápido possível. Dessa forma, eles se encaixam no TOC sem quebras.

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

• Usar a primeira letra maiúscula para títulos

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

• Tente fazer com que os títulos sejam baseados em tarefas ou acionáveis. Se os títulos forem conceituais, eles poderão ser baseados no entendimento, mas escreva conforme 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 da compilação, o Bazel imprime os destinos solicitados.
  • Não: no final do build, o Bazel imprime os destinos solicitados.

• Mantenha a consistência. Não dê nomes novos 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: nesta página, explicamos como instalar o Bazel no Windows.
  • Não: (nenhuma frase de introdução.)

• 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 usuários, ou seja, 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 um 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, atualize 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 dele.

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 desativadas rapidamente e podem estar incorretas se for uma projeção futura. Em vez disso, especifique um nível de versão, como "O Bazel X.x e versões mais recentes oferecem suporte a <feature> ou um link de 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 presente. Evite o tempo no passado ou no futuro, a menos que seja absolutamente necessário para fins de clareza.

  • Sim: o Bazel emite um erro quando encontra dependências que não obedecem a 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 a voz ativa (em que um sujeito age sobre um objeto) e não a voz passiva (em que um objeto é afetado por um sujeito). 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 criar Y.
  • Não: X é iniciado pelo Bazel e, depois, Y é criado com a saída.

Tom

Escreva em um tom amigável aos negócios.

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

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

• Evite uma 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:

Links

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

  • Sim: para mais detalhes, consulte [Como instalar o Bazel].
  • Não: para mais detalhes, consulte [este link].

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

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

Listas

• Usar uma lista ordenada para descrever como realizar uma tarefa com etapas
• Use uma lista não ordenada para listar itens que não são baseados em tarefas. (Ainda deve haver uma ordem de classificação, como alfabética, importância etc.)
• Escreva com estrutura paralela. Exemplo:
  1. Crie frases para todos os itens da lista.
  2. Comece com verbos que têm o mesmo tempo.
  3. Use uma lista ordenada se houver etapas a seguir.

Marcadores de posição

• Use sinais de maior e menor para indicar uma variável que os usuários devem 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 amostras de código complicadas, 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 sumário manual.

Código

Os exemplos de código são os melhores amigos dos desenvolvedores. Você provavelmente já sabe como escrevê-los, 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, 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 um exemplo de código.
• Em Markdown, especifique o tipo de bloco de código adicionando a linguagem da amostra.

```shell
...

• Separar 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 do 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".