Código

Execute cada comando antes de publicar

Um bloco de código não testado é um palpite com aparência de autoridade. A prosa sinaliza incerteza com palavras; um bloco de código não sinaliza nada, e o leitor o executa com confiança total. Na página, um comando inventado é idêntico a um comando testado. A diferença aparece quando o comando falha, na máquina do leitor.

Execute cada comando e cada snippet antes de publicar a página. Quando não puder executar um, não o publique. Uma página que afirma menos, e acerta em tudo o que afirma, vale mais do que uma página que adivinha.

Componha, não invente

Um bloco de código mistura dois tipos de conteúdo: os fatos que ele carrega e a sintaxe que os expressa. A sintaxe de ferramenta necessária para expressar um fato com fonte é composição, não invenção. Flags de curl, um cabeçalho Content-Type para um dado corpo JSON e as aspas do shell entram nessa categoria. Um novo valor de produto, campo, endpoint ou valor padrão é invenção.

Para a regra de que cada dado rastreia até uma fonte, consulte Escolha de palavras.

Torne os placeholders óbvios e consistentes

Um placeholder tem um trabalho: o leitor precisa ver de imediato que deve substituir aquele valor. Dois formatos cumprem esse trabalho: colchetes com maiúsculas, [TOKEN VALUE], e os sinais < e > com palavras minúsculas, <your-bucket-name>. Use um único formato para todos os placeholders de uma página; três convenções na mesma página não ensinam nenhuma.

Cada tipo de valor tem uma forma reservada:

As faixas de IP são reservadas para documentação e não roteiam para nenhum destino.

• Incorreto: --token abc123
• Correto: --token [TOKEN VALUE]

abc123 parece um valor que pode funcionar, e um leitor com pressa o cola sem alterar. [TOKEN VALUE] não passa por um valor real. O pior placeholder é um valor falso realista, porque esconde que existe algo para substituir.

Introduza cada bloco de código

Uma frase antes do bloco declara o que o código faz. Um bloco de código sem contexto é um trecho que o leitor precisa decifrar antes de decidir se executa.

Marque a linguagem, e nomeie um arquivo só quando existir um

A tag de linguagem de um fence define o destaque de sintaxe e nomeia a linguagem na barra acima de qualquer bloco de duas ou mais linhas: bash mostra Shell, json mostra JSON. Dê uma tag a todo fence, e text a um output sem linguagem. Um bloco de uma linha não mostra números de linha, nem barra se não tiver title.

Adicione title="..." só quando o bloco for um arquivo que o leitor salva, como title="azion.config.js". O nome do arquivo toma o lugar da linguagem na barra. As props estão em Componentes.

Deixe o prompt fora do que o leitor copia

Nenhum $ ou > antes de um comando. O leitor cola a linha com o prompt junto, e o comando falha. Um prompt só cabe em saída mostrada em um fence, onde reproduz uma sessão real.

Escreva comentários como prosa

Um comentário dentro de um snippet segue o idioma da página e as regras de frase, e diz por quê, não o quê. Um comentário que repete a linha abaixo dele não acrescenta nada.

Mantenha credenciais fora dos blocos de código

Nenhuma credencial real aparece na documentação: nem uma ativa, nem uma expirada, nem uma revogada. Na página, uma credencial expirada é indistinguível de uma ativa, e por isso a proibição cobre todas por igual. Um valor inventado com formato realista é proibido pela mesma razão: nenhum leitor, e nenhum scanner, o distingue de um vazamento. Escreva o placeholder: [TOKEN VALUE].

Esta seção não mostra um exemplo incorreto. Uma credencial falsa realista em um guia de estilo ainda é uma credencial falsa realista em documentação pública.