Guia de estilo de documentos do Bazel

Informar um problema Ver código-fonte Nightly · 7.4 . 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.

Princípios de definição

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.
  • Consistente. 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 sumário sem serem agrupados.

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

  • Use letras maiúsculas 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 mais rapidamente.

    • Sim: esta página explica como instalar o Bazel no Windows.
    • Não: (nenhuma frase de introdução.)

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

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, atualize 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 expressão "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, 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: o X é iniciado pelo Bazel e, em seguida, o Y é criado com a saída.

Tom

Escreva com um tom comercial amigável.

  • Evite 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. Os links longos ou snippets de código podem ser mais longos, mas precisam começar em uma nova linha. Exemplo:

  • Use um texto descritivo de 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 precisa haver uma ordem de classificação, como ordem alfabética, importância etc.
  • Escreva 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 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 bolding.
    • Sim: bazel help <command>: mostra ajuda e opções para <command>
    • Não: bazel help command: imprime ajuda e opções para "command".