Guia de estilo de documentos do Bazel

Agradecemos por contribuir com a documentação do Bazel. Ele serve como um guia de estilo de documentação rápido para você começar. Para perguntas de estilo não respondidas por este guia, siga o Guia de estilo da documentação do desenvolvedor do Google.

Princípios de definição

Os documentos do Bazel precisam seguir estes princípios:

  • Concisão. Use o mínimo de palavras possível.
  • Claro. Use uma linguagem simples. Escreva sem jargões para um nível de leitura do quinto ano.
  • Consistentes. Use as mesmas palavras ou frases para conceitos repetidos em todos os documentos.
  • Correto. Escreva de uma maneira em que o conteúdo permaneça correto pelo maior tempo possível, evitando informações com base em tempo e promessas para o futuro.

Gravação

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

Títulos

  • Os cabeçalhos no nível da página começam no H2. Os cabeçalhos do T1 são usados como títulos das páginas.

  • Torne os cabeçalhos o mais curtos possível. Dessa forma, eles se encaixam no TOC sem embrulhar.

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

  • Usar letra maiúscula apenas na primeira palavra nos títulos

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

  • Tente criar títulos baseados em tarefas ou acionáveis. Se os títulos forem conceituais, podem ter como base a compreensão, mas escreva no que o usuário faz.

    • Sim: preservando a ordem do gráfico
    • Não: na preservação da ordem do gráfico

Nomes

  • Use letras maiúsculas em substantivos próprios, como Bazel e Starlark.

    • Sim: no final do build, o Bazel imprime os destinos solicitados.
    • No: no final do build, o Bazel imprime os destinos solicitados.

  • Mantenha a consistência. Não inclua novos nomes para conceitos que já existem. 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 um propósito, e isso deve ser definido 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: sem frase introdutória.

  • No final da página, diga ao leitor o que fazer em seguida. Nas páginas em que não há ações claras, é possível incluir links para conceitos, exemplos semelhantes ou outros meios de análise.

Assunto

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

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

    • Sim: para criar código Java usando o Bazel, você precisa instalar um JDK.
    • MAIBE: para que os usuários criem código Java com o Bazel, eles precisam instalar um JDK.
    • No: para que um usuário crie código Java com o Bazel, ele precisa instalar um JDK.

  • Se o público NÃO for de usuários gerais do Bazel, defina o público no início da página ou na seção. Outros públicos-alvo podem incluir mantenedores, colaboradores, migrantes ou outras funções.

  • Evite "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 alterações dos usuários do Bazel.

Temporal

Sempre que possível, evite termos que orientem as coisas no tempo, como mencionar datas específicas (2o trimestre de 2022) ou dizer "agora", "atualmente" ou "em breve". Eles se desativam rapidamente e podem ser incorretos 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 para <recurso> ou um link de problema no GitHub.

  • Sim: o Bazel 0.10.0 ou mais recente é compatível com o armazenamento em cache remoto.
  • Não: em breve, o Bazel será compatível com o armazenamento em cache remoto, provavelmente em outubro de 2017.

Tense

  • Use o presente. Evite o tempo passado ou futuro, a menos que seja absolutamente necessário para maior clareza.

    • Sim: o Bazel emite um erro quando encontra dependências que não estão em conformidade com essa regra.
    • No: 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 uma pessoa atua sobre um objeto, e não a voz passiva, em que um objeto faz a interação. 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 criar Y.
    • No: X é iniciado pelo Bazel. Depois, Y é criado com a saída.

Tom

Escreva com um tom voltado para os negócios.

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

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

  • Evite linguagem excessivamente formal. Escreva como se você estivesse explicando o conceito para alguém que tem curiosidade sobre tecnologia, mas não sabe os detalhes.

Formatação

Tipo de arquivo

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

  • Use um texto descritivo para o 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 [Como instalar o Bazel].
    • Não: veja mais detalhes [aqui].

  • Encerre 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 se baseiam em tarefas. (Ainda deve haver uma ordem de classificação, como alfabética, importância etc.)
  • Escreva com estrutura paralela. Exemplo:
    1. Coloque todos os itens da lista em frases.
    2. Comece com verbos que possuem o mesmo tempo.
    3. Use uma lista ordenada se houver etapas a serem seguidas.

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>: mostra ajuda e opções para <command>.
    • Não: command do bazel help: mostra a ajuda e opções para "comando"

  • Use marcadores que façam sentido no contexto, principalmente para amostras de código complicadas.

Índice

Use o TOC gerado automaticamente aceito pelo site. Não adicione um TOC 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, é possível 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. Eliminar todo o texto redundante ou desnecessário de uma amostra de código.
  • No 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 embutido

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