Guia de estilo de documentos do Bazel

Agradecemos por contribuir com a documentação do Bazel. Ele serve como um guia rápido de estilo de documentação para você começar. Para perguntas de estilo não respondidas por este 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:

  • 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.
  • Consistentes. 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.

Gravação

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

Títulos

  • Os títulos no nível da página começam no 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 tornar os cabeçalhos 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: Preservando a ordem do gráfico
    • Não: preservar a ordem do gráfico

Nomes

  • Use letras maiúsculas em nomes próprios, como Bernardo e Starlark.

    • Sim: no final da compilação, o Bazel imprime os destinos solicitados.
    • Não: no final da compilação, 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 a emissão de 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, que 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 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, é possível incluir links para conceitos, exemplos ou outros caminhos semelhantes para análise.

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.

  • Use o nome "você" para se referir ao leitor. Se, por algum motivo, não for possível usar "você", use uma linguagem de gênero neutro, como.

    • Sim: para criar código Java usando o Bazel, você precisa instalar um JDK.
    • MAYBE: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 seu 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, migrantes ou outros papéis.

  • Evite usar "nós". Nos documentos do usuário, não há autor; apenas diga à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 dele.

Temporal

Sempre que possível, evite termos que orientam as coisas no tempo, como mencionar datas específicas (2o trimestre de 2022) ou dizer "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 posterior é compatível com armazenamento em cache remoto.
  • Não: em breve, o Bazel oferecerá suporte ao armazenamento em cache remoto, 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, emitirá um erro.

  • Sempre que possível, use a voz ativa, em que a pessoa age sobre um objeto, e não a voz passiva, quando o objeto é interagido. Geralmente, a voz ativa deixa as frases mais claras, porque mostra quem é 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 a compilação 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 usar linguagem coloquial. É mais difícil traduzir frases específicas para o inglês.

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

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

Formatação

Tipo de arquivo

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

  • 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: confira mais detalhes [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

  • 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.)
  • Escrever com estrutura paralela. Exemplo:
    1. Coloque todos os itens da lista em sentenças.
    2. Comece com verbos que têm o mesmo tempo.
    3. Se houver etapas a serem seguidas, use uma lista ordenada.

Marcadores de posição

  • Use sinais de maior e menor para indicar uma variável que os usuários devem mudar. Em Markdown, faça o escape dos colchetes angulares com uma barra invertida: \<example\>.

    • Sim: bazel help <command>: exibe ajuda e opções para <command>.
    • Não: bazel help command: exibe 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 aceito pelo 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 negrito.
    • Sim: bazel help <command>: exibe ajuda e opções para <command>.
    • Não: bazel help command: exibe ajuda e opções para "command".