Formatação de texto

Use negrito para labels da interface e nomes de produto

O negrito marca um label que o leitor precisa encontrar na tela e marca um nome de produto. Todo o resto fica em texto simples, porque o negrito de ênfase compete com esses dois usos. Um parágrafo com três frases em negrito não tem nenhuma.

• Incorreto: Você **precisa** limpar o cache **antes** do deploy da **nova versão**.
• Correto: Limpe o cache antes do deploy da nova versão.

O negrito cumpre o seu papel quando aponta para a interface: Selecione **Save** para aplicar a alteração. O leitor sabe qual palavra procurar na tela.

Use itálico para valores da interface e termos definidos

O itálico marca um valor ou opção que o leitor escolhe na interface: Defina a permissão como _Read Only_. O label fica em negrito; o valor fica em itálico.

O itálico também marca um termo no momento em que a página o define: Uma *cache key* identifica um objeto no cache. Depois da definição, o termo aparece em texto simples. Itálico em qualquer outro lugar dilui os dois sinais, e por isso a documentação o usa raramente.

Use monoespaçado para código e valores digitados

O monoespaçado marca código e tudo o que o leitor digita: comandos, caminhos, nomes de campo, flags, headers, códigos de status e nomes de arquivo.

Nomes de ferramenta ficam em monoespaçado, nunca em negrito: azion, npm, curl. O negrito nomeia um produto; o monoespaçado nomeia o comando que o leitor executa.

Os três estilos dividem o trabalho: negrito para o label, itálico para o valor, monoespaçado para o texto digitado.

Nunca sublinhe, e nunca coloque um link em negrito

O sublinhado pertence só aos links. Uma palavra sublinhada que não é link parece um link quebrado, e o leitor clica nela.

Também não coloque em negrito o texto dentro de um link. O link já tem o próprio estilo, e o negrito por cima dele compete com o negrito que marca labels de interface.

• Incorreto: Consulte [**Configurações de cache**](/pt-br/documentacao/plataforma/applications/cache/cache-settings/).
• Correto: Consulte [Configurações de cache](/pt-br/documentacao/plataforma/applications/cache/cache-settings/).

Formate os links internos

Um link interno é absoluto, começa com o prefixo de idioma e termina com barra.

• Incorreto: [Applications](../build/applications)
• Correto: [Applications](/pt-br/documentacao/plataforma/applications/)

Os caminhos de assets seguem outra regra. Uma mesma imagem serve as duas versões de idioma de uma página. Por isso, o caminho é absoluto a partir da raiz, sem prefixo de idioma.

• Correto: /assets/docs/images/uploads/diagram.png

Escreva textos de link que nomeiam o destino

O leitor decide se segue um link apenas pelo texto do link. “Clique aqui” nomeia a ação em vez do destino, e uma URL solta esconde o destino na sintaxe. Os dois obrigam o leitor a ler ao redor do link.

• Incorreto: Para saber mais sobre as regras de frase, [clique aqui](/pt-br/documentacao/guia-de-estilo/escrita/estrutura-de-frases/).
• Correto: Os limites de frase estão definidos em [Estrutura de frases](/pt-br/documentacao/guia-de-estilo/escrita/estrutura-de-frases/).

Duas formas padrão cobrem quase toda frase de link, sempre com o verbo consulte:

• Para mais informações, consulte [Título](/pt-br/documentacao/.../).
• Para <fazer algo>, consulte [Título](/pt-br/documentacao/.../).

Não escreva Saiba mais sobre..., Para ler mais..., clique aqui, esta página nem uma URL solta no texto. O texto do link nomeia o destino.

Um link em seção de encerramento carrega o seu motivo. Em um card de ## Próximos passos ou em uma linha de ## Recursos relacionados, o título é o destino e o texto é uma frase sobre o que o leitor encontra lá.

O texto de link é único na página. Dois links com o mesmo texto precisam ir para o mesmo lugar, porque o leitor que vê as mesmas palavras espera o mesmo destino.

Links dentro de um parágrafo apontam para páginas da documentação. Links externos ficam reunidos no fim da página ou da seção, para o fluxo de leitura nunca sair da documentação no meio de uma tarefa.

Aponte a primeira menção de outro elemento documentado

Quando a prosa nomeia um produto, um recurso da plataforma ou uma feature que tem página própria, a primeira menção na página aponta para essa página: Configure um [firewall](/pt-br/documentacao/plataforma/firewall/) para proteger a aplicação. As menções seguintes ficam em texto simples, ou em negrito onde a regra de nomes de produto pede.

O link substitui o negrito nessa primeira menção, porque o texto dentro de um link nunca fica em negrito. Um leitor que encontra um nome desconhecido sempre tem a página dele a um clique.

Use asides para o que o texto não comporta

Um aside carrega informação útil que não cabe no fluxo. As quatro variantes dividem o trabalho:

Três limites mantêm os asides legíveis. Use no máximo um aside de cada tipo por seção. Mantenha um aside em até três parágrafos curtos. Nunca coloque um título dentro de um aside.

Um aside nunca carrega a resposta principal. O leitor que pula todos os asides ainda precisa completar a tarefa somente com o fluxo.

Numere uma lista apenas quando a ordem importa

Uma lista numerada promete ordem: o leitor executa o passo 2 depois do passo 1. Quando a ordem não importa, a lista usa marcadores. Quando existe um único item, escreva uma frase, porque uma lista de um item é uma frase com um marcador na frente.

As regras de frase para passos estão em Estrutura de frases.

Mantenha os itens da lista paralelos

Os itens de uma lista compartilham uma gramática: todos começam com verbo, ou todos começam com substantivo. A gramática mista obriga o leitor a reinterpretar cada item, e a lista fica mais lenta de percorrer do que um parágrafo.

Incorreto:

Correto:

Use tabelas para conteúdo enumerável

Campos, limites, flags, valores padrão e códigos de status pertencem a tabelas. O leitor de referência percorre uma tabela; ele não a lê. Duas regras protegem esse modo de leitura.

Escreva uma coluna com estrutura consistente. Uma coluna com Ativa o cache, depois esta opção liga os logs, depois compressão ligada descreve um mesmo tipo de fato em três formas. Cada forma nova obriga uma leitura de verdade. Escreva Ativa o cache, Ativa os logs, Ativa a compressão.

Declare a unidade e o valor padrão de cada valor. Um limite sem unidade não é um fato: uma célula com 100 deixa o leitor adivinhar entre megabytes, segundos e requisições. Escreva 100 MB e declare o valor padrão quando existir um.

Introduza cada tabela com uma frase que diz o que ela mostra. Uma tabela que chega sem contexto é um dado que o leitor precisa decifrar.

Nunca coloque uma tabela no meio de um procedimento numerado. A tabela interrompe a sequência; posicione a tabela antes dos passos ou faça um link para ela.