Escolha de palavras

Corte o vocabulário de enchimento

Algumas palavras aparecem em rascunhos como decoração e não carregam significado técnico. Apague o enchimento e mantenha a frase: “é importante notar que” e “note que” não adicionam nada. Prefira a forma curta: “para” em vez de “a fim de”, “porque” em vez de “devido ao fato de que” e “pode” em vez de “tem a capacidade de”.

Prefira o verbo simples: “use” em vez de “utilize”, e “cubra” em vez de “explore em profundidade”. Troque uma quantidade vaga pela real: nomeie o intervalo em vez de “uma ampla gama de” e conte as opções em vez de “várias”.

• Antes: A fim de aproveitar as várias opções de cache, note que a configuração é simples.
• Depois: Para armazenar conteúdo em cache, defina o TTL e a cache key.

Mantenha uma palavra dessa família quando ela carrega significado técnico. Corte quando ela decora.

Evite adjetivos vazios

Um adjetivo vazio afirma qualidade sem descrever comportamento. Retire o adjetivo e diga o que o produto faz, o que ele suporta ou o que ele cobre. Voz da documentação é a dona da regra de registro. Esta página cobre o vocabulário.

O teste é se a palavra afirma qualidade ou descreve comportamento. “Robust security” pede que o leitor confie em um adjetivo. “A robust retry with exponential backoff” nomeia o mecanismo, e o adjetivo agora descreve algo testável. Mantenha uma palavra que passa nesse teste. Substitua a que não passa.

A mesma falha se esconde em molduras de frase. Escreva “Use para” em vez de “Perfeito para” ou “Essencial para”, e “Use quando” em vez de “Melhor para”. Diga a ação diretamente em vez de “capacita você a”, e retire “moderno”, “seamless” e “de ponta” como modificadores.

• Antes: Applications oferece um cache poderoso e flexível, perfeito para o e-commerce moderno.
• Depois: Applications armazena conteúdo em cache na infraestrutura distribuída da Azion.

Inflação de importância é a mesma falha apontada para um conceito: uma frase sobre a importância de algo no lugar do que ele faz. “O cache desempenha um papel crucial na performance da web moderna” não dá ao leitor nada para fazer. Diga o que a coisa faz e quais são os limites.

Corte os padrões de enchimento

Cinco padrões adicionam palavras sem adicionar informação.

Particípio de enchimento é uma oração final com gerúndio: “…reduzindo a latência e melhorando a performance, garantindo uma experiência melhor.” Corte a oração e mantenha a afirmação mensurável. A regra desse padrão no nível da frase está em Estrutura de frases.

Paralelismo negativo é a forma “Não é só X, é Y.” Diga Y.

Falsos intervalos conectam itens que não estão em uma escala: “da configuração ao deploy ao monitoramento”. Liste o conjunto real.

”Você pode” sem conteúdo promete sem entregar: “Você pode configurar várias opções.” Nomeie as opções ou aponte para a página que as nomeia.

Conclusões genéricas repetem a página sem adicionar nada. Termine no último fato concreto ou em um link que valha a pena seguir.

Varie a forma de frases consecutivas

Duas frases seguidas que começam com as mesmas palavras, ou que compartilham a mesma forma gramatical, soam como um template mesmo quando todos os fatos estão certos:

• Antes: Um data center que tem uma cópia válida responde do cache. Um data center que não tem uma cópia válida busca o objeto na origem.
• Depois: Quando um data center tem uma cópia válida, ele responde do cache. Caso contrário, o data center busca o objeto na origem.

Três técnicas quebram o padrão: comece pela condição, e não pelo sujeito; contraste com um conectivo como Caso contrário em vez de nomear o sujeito duas vezes; e deixe uma frase carregar duas orações quando elas são um só pensamento. Um parágrafo cujas frases têm todas o mesmo comprimento médio soa do mesmo jeito, então varie o comprimento e prefira frases curtas.

Nomeie as coisas nos títulos

Um título nomeia uma coisa ou uma tarefa. Uma pergunta retórica não faz nenhuma das duas.

• Antes: O que é cache?
• Depois: Cache
• Antes: Por que usar o Tiered Cache?
• Depois: Quando usar o Tiered Cache

Evite estas palavras em qualquer página

Não chame uma tarefa de “simples”, “fácil” ou “óbvia”, e não suavize um passo com “basta”, “é só” ou “simplesmente”. Se a tarefa fosse fácil, o leitor não estaria aqui, e essas palavras dizem a um leitor travado que ele deveria se envergonhar.

Não escreva “por favor”. A documentação instrui. Ela não pede.

Não ancore uma página no tempo com “atualmente”, “no momento da escrita”, “em breve”, “agora disponível”, “recentemente” ou “novo” como modificador. Todas envelhecem mal, e ninguém volta para corrigir. Nenhum mês ou ano aparece fora de um changelog: diga o que é verdade e deixe o changelog carregar a linha do tempo. Uma data gerada por um passo de build, como a coluna de última atualização em um hub de Guias e tutoriais, é exceção, porque nada escrito à mão envelhece ali.

Escreva “por exemplo” e “isto é”, nunca “e.g.” nem “i.e.”.

Use os verbos da interface

Cada ação de interface recebe um verbo, o mesmo em todas as páginas. A tabela registra a regra do texto em inglês, a fonte canônica:

Em inglês, “enable” e “disable” continuam legítimos para descrever estado em prosa: “When WAF is enabled on the firewall, requests pass through it.”

Os procedimentos publicados em português usam “acesse”, “selecione”, “digite” e “defina”; nunca “clique”.

Não use linguagem direcional. Nomeie o elemento, conforme Acessibilidade.

A gramática de passos que usa esses verbos está em Procedimentos.

Use linguagem inclusiva

A documentação trata o leitor por “você”, e o leitor genérico nunca precisa de um pronome de gênero. No texto em inglês, um terceiro genérico — quem ataca, quem desenvolve — recebe “they”, nunca “he” ou “she”.

Expressões com marca de gênero e expressões capacitistas seguem a mesma regra. Escreva validate, não sanity check.

Um cargo ou uma profissão usa um substantivo neutro. Escreva operador de câmera, não uma forma marcada por gênero.

Substitua um termo técnico carregado quando a indústria aceita uma alternativa. Os termos ficam em inglês porque o texto em inglês é a fonte canônica:

Não use referências culturais nem expressões idiomáticas. Elas fazem sentido em um único lugar e não sobrevivem à tradução. Cada página aqui é publicada em dois idiomas, conforme Páginas bilíngues.

Retire o artigo antes de um nome de produto

Um nome de produto é um nome próprio, então não leva artigo.

• Incorreto: Acesse o Azion Console.
• Correto: Acesse Azion Console.

O artigo volta quando um substantivo comum acompanha o nome, porque aí ele pertence a esse substantivo: O bucket do Object Storage guarda o resultado do build.

Use a grafia do inglês americano

Nos trechos em inglês, escreva organize, behavior e license. Grafias britânicas entram em páginas copiadas da documentação de fornecedores, então confira as que diferem.

Expanda as siglas no primeiro uso

O primeiro uso em cada página escreve o termo por extenso e coloca a sigla entre parênteses: time to live (TTL). Depois disso, apenas a sigla. O leitor chega a qualquer página diretamente, por um resultado de busca, e uma definição em outra página não existe para ele.

Nomes de produto não são siglas. Escreva o nome conforme as regras em Terminologia da documentação e não o expanda.

Confirme cada dado

Um dado inventado é a pior falha da documentação. Um limite, um valor padrão, um nome de campo, uma flag ou uma mensagem de erro inventados parecem iguais aos corretos. O leitor descobre a diferença só quando tenta usar e falha.

Cada número, nome de campo e comando vem de algum lugar que você consegue apontar: o próprio produto, a API dele ou o time que cuida dele. Quando não consegue confirmar um valor, deixe-o de fora. Uma página que diz menos é recuperável. Uma página com um valor errado e confiante não é, porque ninguém sabe que precisa conferir.

Os nomes de produto seguem regras próprias, em Terminologia da documentação.