ddofer/escrever-para-leitores

Escrever para leitores

Seu leitor não estava lá. Eles conhecem a área, não o seu projeto, e leem superficialmente. Para escolha de palavras, aplique plain-words.

• Edição, revisão ou limpeza de um artigo, relatório ou página existentes: siga references/editing-pass.md, com as regras abaixo como sua lista de verificação.
• Escrever ou editar um artigo: leia também references/paper.md.

Ordem

• Comece pela descoberta: o que aconteceu e sua magnitude. Destaque a nova ideia ou capacidade; uma comparação só lidera quando ela é a contribuição. Abra com o problema apenas se uma introdução for necessária; nunca uma genérica. Não narre o histórico do projeto ou um registro do que foi executado.
• Os títulos afirmam a conclusão em um relatório ("Planos mais baratos vendem mais", não "Análise de preços"); um relatório longo abre com uma lista numerada de descobertas.
• Resumos e sumários executivos permanecem em alto nível: descobertas em palavras, o número que o leitor citaria, nulos em palavras, por que cada um importa. Corresponda ao comprimento solicitado. Termine com uma afirmação simples que o leitor lembrará.
• E-mails e entregas são uma lista curta de decisões: o que fazer, o quão difícil é cada correção, qual opção exige menos trabalho manual.
• O texto principal é autossuficiente. Defina cada termo e comparador onde ele aparece pela primeira vez, nunca primeiro em um apêndice. Um relatório longo termina com um breve glossário.

Conteúdo

• Dê a cada número algo para comparar: "25,6% de precisão (o acaso é 10%)".
• Diga o quão grande é uma descoberta, mesmo quando pequena.
• Mostre um exemplo real por descoberta. Mantenha estudos de caso, surpresas e resultados negativos verificados.
• Explique um método uma vez, onde ele aparece pela primeira vez: uma linha sobre como; o porquê apenas onde o leitor perguntaria ou seria enganado. Divulgue exclusões que definem a população ou o denominador; não defenda escolhas rotineiras.
• Sem avisos de conteúdo ou notas sobre seu próprio processo, a menos que o veículo ou o usuário os solicite. Se um limite ou subconjunto foi escolhido após ver os resultados, declare a regra claramente, uma vez.
• Declare um limite uma vez, ao lado da afirmação que ele limita, e apenas se mudar o que o leitor deve acreditar. Mantenha condições que definem o resultado ("apenas em 2024"). Um único quase-acerto sob uma verificação de robustez não rebaixa um título; uma reversão sim.
• Estreite uma afirmação exagerada em vez de atenuá-la: mantenha a parte firme, descarte a parte instável.
• Não sabote a descoberta. Não conceda nada além do que os dados mostram. Não adicione contraste que ninguém pediu, a menos que mude o que o leitor deve acreditar. Se uma verificação enfraquece uma história, proponha corrigir ou estender a análise antes de atenuá-la ou descartá-la; não mude a análise você mesmo.
• Sem blocos densos. Um parágrafo faz um ponto e pode ser lido uma vez, em velocidade. Divida um parágrafo que empilha achados ou condições; uma sequência de números vai em uma tabela ou lista. Marcadores são adequados quando os itens são paralelos.
• Uma história. Descarte histórias secundárias. Verificações secundárias e exceções recebem uma frase no texto principal; seus detalhes vão para um apêndice.
• Compare o que é comparável. Números de conjuntos de dados ou pessoas diferentes recebem sua própria frase ou tabela. Nunca os coloque lado a lado como se um causasse o outro.
• Tudo deve se justificar. Cada palavra, frase, parágrafo, item de lista, seção, coluna de tabela, painel de figura e cláusula de legenda deve mudar o que o leitor acredita ou como eles leem algo. Pergunte de cada um: o que o leitor perderia sem isso? Se nada, corte; não comprima.
• Diga cada coisa uma vez. Um número vive em uma tabela ou no texto, não em ambos; no texto principal ou no apêndice, não em ambos. Uma descoberta é declarada por completo uma vez; o resumo, introdução e sumário repetem apenas seu número-chave.
• Não adicione nada que não esteja nas fontes. Nunca invente uma citação ou resultado; deixe um espaço reservado marcado para o autor.

Figuras e tabelas

• Cada painel faz um ponto que o texto não pode fazer tão bem. Torne a métrica, a direção melhor e as linhas de base óbvias.
• Nomes reais, não códigos; o gráfico mais simples; eixos intitulados; um esquema de rótulo, combinando com a legenda e o texto. Coloque um rótulo direto próximo à série que nomeia.
• Mostre todos os subconjuntos ou declare a regra que os selecionou.
• Em um relatório, o título da figura diz o que é mostrado. A legenda diz como lê-lo e não repete os métodos.

Antes de entregar

Leia como o leitor. Para cada frase: eles sentiriam falta dela? Cada número diz "comparado com o quê"? Então execute plain-words. Não altere nenhum número. Se algo estiver faltando ou dois números discordarem, informe o autor em vez de preencher a lacuna.