Guia de estilo de documentos do Bazel

Agradecemos por contribuir com a documentação do Bazel. Este é um guia de estilo de documentação rápido para você começar. Para dúvidas sobre estilo que não foram respondidas neste guia, siga o guia de estilo da documentação para desenvolvedores do Google.

Definir princípios

A documentação do Bazel precisa seguir estes princípios:

• Conciso. Use o menor número possível de palavras.
• Limpar. Use uma linguagem simples. Escreva sem jargões, em um nível de leitura adequado para estudantes dessa faixa etária.
• Consistente. Use as mesmas palavras ou frases para conceitos repetidos em toda a documentação.
• 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.

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.)

• Crie cabeçalhos curtos. Assim, eles cabem no sumário sem quebrar a linha.

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

• Use letra maiúscula apenas na primeira palavra nos cabeçalhos

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

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

  • Sim: preserva a ordem do gráfico
  • Não: sobre a preservação da ordem dos gráficos

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 "terminal" e "linha de comando" na mesma 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 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, inclua links para conceitos, exemplos ou outras formas de exploração semelhantes.

Assunto

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

• Use "você" para se referir ao leitor. Se por algum motivo você não puder usar "você", use uma linguagem neutra em relação a gênero, como "a pessoa".

  • Sim: para criar código Java usando o Bazel, é necessário instalar um JDK.
  • TALVEZ:para criar código Java com o Bazel, os usuários precisam instalar um JDK.
  • Não: para criar código Java com o Bazel, o usuário 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-alvo podem incluir mantenedores, colaboradores, migradores ou outras funções.

• Evite usar "nós". Na documentação do usuário, não há autor. Basta informar às pessoas o que é possível.

  • Sim: à medida que o Bazel evolui, você precisa atualizar a base de código para manter a compatibilidade.
  • Não: o Bazel está em constante evolução, e vamos fazer mudanças que às vezes serão incompatíveis e vão exigir algumas alterações dos usuários.

Temporal

Sempre que possível, evite termos que orientam as coisas no tempo, como referenciar datas específicas (2º trimestre de 2022) ou dizer "agora", "atualmente" ou "em breve". Esses dados 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 para um problema do GitHub.

• Sim: o Bazel 0.10.0 ou versões mais recentes oferecem suporte ao 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 usar o tempo passado ou futuro, a menos que seja absolutamente necessário para a 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, 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 recebe a ação de um sujeito). Em geral, 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, depois, Y é criado com a saída.

Tom

Escreva com um tom adequado para negócios.

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

  • Sim: conjuntos de regras bons
  • Não: entã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, faça quebras de linha a cada 80 caracteres. Links longos ou snippets de código podem ser mais longos, mas precisam começar em uma nova linha. Exemplo:

Links

• Use um texto 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 deve haver uma ordem, como alfabética, de importância etc.
• Escreva com estrutura paralela. Exemplo:
  1. Transforme todos os itens da lista em frases.
  2. Comece com verbos no mesmo tempo verbal.
  3. Use uma lista ordenada se houver etapas a seguir.

Marcadores de posição

• Use colchetes angulares para indicar 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>: ajuda e opções de impressão para <command>
  • Não: bazel help comando: imprime ajuda e opções para "comando"

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

Índice

Use o sumário gerado automaticamente compatível com o site. Não adicione um sumário manual.

Código

Exemplos de código são os melhores amigos dos desenvolvedores. Você provavelmente já sabe como escrever esses comandos, mas aqui estão algumas dicas.

Se você estiver fazendo referência a um pequeno snippet de código, incorpore-o 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.
• Em 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 trechos de código.
• Use o estilo de código inline em vez de itálico, "aspas" ou negrito.
  • Sim: bazel help <command>: ajuda e opções de impressão para <command>
  • Não: bazel help comando: imprime ajuda e opções para "comando"