Guia de estilo de documentos do Bazel

Informar um problema Mostrar fonte Por noite · 7,3 · 7,2 · 7,1 · 7,0 · 6,5

Agradecemos por contribuir com a documentação do Bazel. Isso serve como um guia de estilo da documentação para você começar. Para perguntas sobre estilo, respondidas por este guia, siga as Guia de estilo da documentação do desenvolvedor 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. Escrever sem jargões para o 5o ano nível de leitura.
  • Consistentes. Usar as mesmas palavras ou frases para conceitos repetidos ao longo dos documentos.
  • Correto. Escrever de uma forma que mantenha o conteúdo correto pelo tempo ao evitar informações e promessas com base 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 embrulho.

    • 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, pode se basear 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. Onde 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 deve ter uma finalidade, que deve ser definida na desde o 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 houver uma ação clara, é possível incluir links para conceitos semelhantes, exemplos ou outros caminhos para 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 o software.

  • Use o nome "você" para se referir ao leitor. Se por algum motivo não puder usar "você", usam linguagem de gênero neutro, como acontece.)

    • 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 um usuário criar código Java com Bazel, ele(a) precisa instalar um JDK.

  • Caso seu público NÃO seja composto por 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 outros cargos.

  • Evite usar "nós". Nos documentos do usuário, não há autor. diga às pessoas o que é sempre que possível.

    • Sim: à medida que o Bazel evolui, você precisa atualizar sua base de código para manter compatibilidade.
    • Não: o Bazel está evoluindo, e vamos fazer mudanças nele que horários serão incompatíveis e exigirão algumas alterações dos usuários do Bazel.

Temporal

Sempre que possível, evite termos que orientam as coisas no tempo, como fazer referência datas específicas (2o trimestre de 2022) ou dizendo "agora", "atualmente" ou "em breve". Estes são fica desatualizado rapidamente e pode estar incorreto se for uma projeção futura. Em vez disso, especificar um nível de versão, como “Bazel X.x e posteriores têm suporte <feature> ou um link do problema no GitHub.

  • Sim: o Bazel 0.10.0 ou mais recente oferece suporte armazenamento em cache remoto.
  • Não: em breve, o Bazel será compatível com o controle remoto. em cache, 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 esclarecimento.

    • Sim: o Bazel emite um erro quando encontra dependências que não obedecem a essa regra.
    • Não: se o Bazel encontra uma dependência que não estiver em conformidade com essa regra, o Bazel vai emitir um erro.

  • Sempre que possível, use voz ativa (quando a pessoa age sobre um objeto) e não voz passiva, em que um sujeito atua sobre um objeto. Geralmente, A voz ativa deixa as frases mais claras, porque mostra quem é responsável. Se O uso da voz ativa diminui a clareza, use a voz passiva.

    • Sim: o Bazel inicia X e usa o para criar Y.
    • Não: X é iniciado pelo Bazel e depois Depois disso, Y será criado com a saída.

Tom

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

  • Evite usar linguagem coloquial. É mais difícil traduzir frases que sejam específicas do 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 conceito para alguém que tem curiosidade sobre tecnologia, mas 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 pode ser mais longo, mas deve começar em uma nova linha. Exemplo:

  • Use o texto descritivo para o 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. (Não há ainda pode ser 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>: impressões ajuda e opções para <command>
    • Não: comando de ajuda do bazel: mostra a 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 aceito pelo site. Não adicione um sumário manual.

Código

Os exemplos de código são melhores amigos. Você provavelmente sabe como escrever esses já, 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 recursos dependente.

Blocos de código

  • Seja breve. Eliminar todo o texto redundante ou desnecessário de um código amostra.
  • 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 de código inline em vez de itálico, "aspas" ou negrito.
    • Sim: bazel help <command>: impressões ajuda e opções para <command>
    • Não: comando de ajuda do bazel: mostra a ajuda e opções para "command"