# 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](/pt-br/documentacao/guia-de-estilo/escrita/voz/) é 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](/pt-br/documentacao/guia-de-estilo/escrita/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: | Use | Not | | ----------------- | ------------------------------------------ | | select | click, hit, tap | | go to | navigate to | | turn on, turn off | enable, disable (for switches and toggles) | | enter | type in, input | | refer to | see, check out | 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](/pt-br/documentacao/guia-de-estilo/escrita/acessibilidade/). A gramática de passos que usa esses verbos está em [Procedimentos](/pt-br/documentacao/guia-de-estilo/escrita/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: | Evite | Use | | ------------ | --------------- | | whitelist | allowlist | | blacklist | blocklist | | master/slave | primary/replica | 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](/pt-br/documentacao/guia-de-estilo/convencoes/paginas-bilingues/). ## 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](/pt-br/documentacao/guia-de-estilo/escrita/terminologia/) 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](/pt-br/documentacao/guia-de-estilo/escrita/terminologia/).