Voz da documentação

Trate o leitor por “você”

A documentação fala com a pessoa que executa o trabalho. A segunda pessoa mantém o leitor dentro da frase, como sujeito do verbo. “O usuário” transforma o leitor em um terceiro e empurra o verbo para o futuro.

• Antes: O usuário criará um bucket.
• Depois: Você cria um bucket.

Use o presente simples

Descreva o comportamento do produto no presente simples. O presente afirma o que a plataforma faz todas as vezes, e é sobre essa afirmação que o leitor age.

• Antes: Applications armazenará conteúdo em cache na infraestrutura distribuída da Azion.
• Depois: Applications armazena conteúdo em cache na infraestrutura distribuída da Azion.

Estrutura de frases é a dona das regras completas de tempos verbais, incluindo a proibição de tempos compostos com verbos auxiliares.

Use a voz ativa

A voz ativa nomeia o ator. A passiva esconde o ator, e o ator costuma ser a resposta que o leitor veio buscar.

• Antes: Uma política de cache é aplicada à requisição.
• Depois: Rules Engine aplica uma política de cache à requisição.

A versão passiva deixa em aberto quem aplica a política: a plataforma, o navegador ou o leitor. Em texto descritivo, a passiva é aceitável apenas quando o ator é desconhecido ou é a própria plataforma. Nunca use a passiva em um passo.

Escreva os passos no imperativo

Um passo é uma instrução, então ele começa pelo verbo: Selecione **Save**., nunca “Você deve selecionar” nem “O botão deve ser selecionado”. Procedimentos é a página dona da gramática de passos.

Descreva comportamento, não qualidade

A documentação descreve comportamento e limites. Ela não vende, porque o leitor já escolheu o produto. Um adjetivo que afirma qualidade não dá ao leitor nada para fazer; um comportamento e um limite dão.

• Antes: Applications oferece capacidades de cache poderosas e flexíveis.
• Depois: Applications armazena conteúdo em cache na infraestrutura distribuída da Azion. O TTL padrão é de 60 segundos.

A reescrita troca dois adjetivos por fatos que o leitor pode testar. As regras de vocabulário estão em Escolha de palavras.

Divida frases longas, não corte palavras

Frases curtas carregam melhor o conteúdo técnico. Curto não é o mesmo que truncado: nunca corte o sujeito, o verbo ou o artigo para encurtar uma frase. Quando uma frase fica longa, divida a frase em duas. Estrutura de frases é a dona desta regra e dos limites de comprimento.

Não use contrações

Em inglês, escreva “do not”, “cannot” e “it is”. Contrações soam casuais e traduzem de forma desigual. O exemplo permanece em inglês porque a regra se aplica ao texto em inglês.

• Antes: You don't need to configure the origin again.
• Depois: You do not need to configure the origin again.

Não escreva “nós”

Nunca escreva “nós”. O ator é “a Azion” ou “você”. “Nós” não nomeia nem a plataforma nem o leitor. Em português, a regra também vale para o verbo na primeira pessoa do plural, como em “recomendamos”.

• Antes: Nós recomendamos um TTL de 60 segundos.
• Depois: A Azion recomenda um TTL de 60 segundos.