Estrutura de frases

Escreva para um leitor que não pode perguntar

A indústria aeroespacial e de defesa publica o ASD-STE100, uma linguagem controlada para escrita técnica. A Issue 9, de 15 de janeiro de 2025, contém 53 regras de escrita em 9 seções. O padrão também traz um dicionário com cerca de 900 palavras aprovadas. Cada palavra desse dicionário tem um significado e uma classe gramatical.

A documentação da Azion segue essas regras porque seus leitores correspondem ao leitor-alvo do padrão. Muitos leitores trabalham em um segundo idioma. Nenhum autor está presente para responder perguntas. Sistemas de busca indexam estas páginas em seções e retornam uma seção, não a página inteira. Uma frase em inglês que segue essas regras também chega ao português com menos desvio.

Ajuste o limite de frase ao tipo de conteúdo

O ASD-STE100 define regras mais rígidas para procedimentos do que para descrições. A Azion aplica essa divisão às quatro formas base.

Um procedimento tem o limite mais rígido porque o leitor executa cada passo sob pressão. Um passo que o leitor lê errado vira uma ação que falha. Os limites contam apenas frases de texto corrido. Células de tabela, código e saída de comando ficam fora da contagem.

Use apenas tempos verbais simples

Escreva com o imperativo, o presente simples, o passado simples e o futuro simples. Não construa tempos compostos com verbos auxiliares. Prefira o presente simples para comportamento do produto, porque a plataforma se comporta da mesma forma em cada requisição.

• Antes: O deploy está sendo processado.
• Depois: O deploy está em andamento.
• Antes: Firewall vai bloquear a requisição.
• Depois: Firewall bloqueia a requisição.

Use termos em -ing apenas como substantivos

Em inglês, um termo em -ing precisa ser um substantivo ou parte de um, como em caching ou request logging. Não use um termo em -ing como verbo nem como oração final. Em português, o mesmo defeito aparece como oração final no gerúndio, que esconde quem age e quando a ação acontece.

• Antes: A função valida o token, retornando um erro quando a assinatura falha.
• Depois: A função valida o token. Quando a assinatura falha, a função retorna um erro.

A mesma lógica vale para títulos de tarefa, que começam com um verbo no imperativo, não com gerúndio. As regras completas estão em Títulos.

Limite os agrupamentos de substantivos a três palavras

Em inglês, uma pilha de quatro ou mais substantivos não tem gramática entre as palavras. O leitor não sabe qual palavra modifica qual. Desfaça o agrupamento com preposições. Um nome de produto conta como uma unidade, então Real-Time Metrics ocupa uma das três posições.

• Antes: the request phase behavior execution order
• Depois: the execution order of the behaviors in the request phase

O português desfaz esses agrupamentos com preposições. Mantenha as preposições na tradução.

Mantenha o sujeito, o verbo e os artigos

Não corte palavras para encurtar uma frase. Uma frase sem sujeito, verbo ou artigos é mais curta e diz menos. Quando uma frase fica longa, divida a frase em duas.

• Antes: Objetos não armazenados em cache são buscados na origem.
• Depois: Quando um objeto não está no cache, a Azion o busca na origem.

Mantenha cada parágrafo em um tópico

Escreva um tópico por parágrafo, em no máximo seis frases. Sistemas de busca cortam as páginas em blocos, e um parágrafo com dois tópicos divide mal em qualquer ponto de corte. Cada fragmento carrega metade do significado.

• Antes: um parágrafo que define a cache key e depois descreve o purge.
• Depois: um parágrafo para a cache key e um segundo parágrafo para o purge.

Use uma lista vertical para uma sequência

Formate três ou mais passos, condições ou alternativas como uma lista numerada ou com marcadores. Uma sequência em uma única frase obriga o leitor a interpretar a ordem e as ações ao mesmo tempo.

Antes:

Salve o arquivo, depois execute o build e depois faça o deploy da aplicação.

Depois:

1. Salve o arquivo.
2. Execute o build.
3. Faça o deploy da aplicação.

Use a mesma palavra para a mesma ação

Escolha um verbo para cada ação e repita esse verbo na página inteira. Uma rotação de sinônimos diz ao leitor que cada verbo nomeia uma ação diferente.

• Antes: Verifique se o build passou. Depois confira se o deploy passou.
• Depois: Verifique se o build passou. Depois verifique se o deploy passou.

Quando uma frase descreve um controle do Console, use o rótulo que o Console mostra. Não melhore o vocabulário da interface.

O ASD-STE100 acompanha suas regras com um dicionário aprovado. As regras 1.5 e 1.12 permitem que um projeto aprove seus próprios nomes técnicos e verbos técnicos. A Azion usa essa permissão: o vocabulário aprovado está em Escolha de palavras e em Terminologia da documentação.

Confira seu rascunho

Confirme cada ponto antes de publicar a página:

• Cada tempo verbal é simples, e o comportamento do produto usa o presente simples.
• Cada termo em -ing funciona como substantivo e nenhuma frase termina em gerúndio.
• Cada agrupamento de substantivos tem no máximo três palavras, com um nome de produto contado como uma.
• Cada frase mantém o sujeito, o verbo e os artigos.
• Cada parágrafo cobre um tópico em no máximo seis frases.
• Cada sequência de três ou mais itens é uma lista vertical.
• Cada ação mantém o mesmo verbo na página inteira.

Fontes

• Site oficial do ASD-STE100: o padrão, com download gratuito.
• About STE: as 53 regras, as 9 seções e a data da Issue 9.
• Guia de estilo de documentação do Google: headings: o caso contra o gerúndio como primeira palavra de um título.