O que penso quando edito (2019)
(evaparish.com)- Editar é o trabalho de verificar, antes de lapidar frases, o que o texto realmente quer dizer e quem é o leitor; os mesmos princípios básicos podem ser aplicados a e-mails, documentos, blogs e romances
- Retomar o ponto principal no começo e no fim do texto, e usar substantivos em vez de demonstrativos como “this/that”, aumenta a clareza porque o leitor não perde o contexto
- Reduzir palavras desnecessárias, transformar instruções em imperativo e dividir frases longas e estruturas com “of/for” faz o significado chegar mais rápido
- Voz passiva, advérbios, jargão e clichês podem obscurecer o agente, o significado exato e o público-alvo; por isso, é melhor trocá-los por verbos concretos e explicações claras
- Uma boa edição não é seguir regras cegamente, mas escolher a linguagem com consciência de acordo com a mensagem que se quer transmitir e eliminar expressões desnecessárias
Defina primeiro o que o texto realmente quer dizer
- Antes de entrar na edição frase por frase, é preciso verificar se o texto está realmente dizendo aquilo que pretende dizer
- Escrever um preâmbulo (preamble) pessoal para cada texto cria um critério de edição
- As perguntas centrais são: “qual é o ponto principal?” e “para quem estou escrevendo?”
- Anote essas informações no topo do documento e compare-as com o conteúdo real durante a escrita e a edição
- Se você não consegue resumir o ponto de uma postagem de blog em uma ou duas frases, será difícil escrever um texto coerente
- Nas aulas de escrita criativa da Writers Studio, cada tarefa inclui um preâmbulo com a voz, o tom e a atmosfera pretendidos, e a avaliação se concentra mais na técnica e em quanto a intenção foi alcançada do que em gosto pessoal
A repetição é um recurso que mantém o leitor engajado
- Mesmo que a ideia principal pareça suficientemente clara, repeti-la no começo e no fim ajuda o leitor a acompanhar melhor o ponto central
- Tutoriais de documentação costumam funcionar bem com uma estrutura que apresenta o que será feito, fornece o procedimento e depois verifica se foi executado corretamente
- Em posts de blog, também funciona apresentar o tema, desenvolvê-lo no corpo do texto e terminar com um breve resumo
- A repetição também é necessária no nível da linguagem
- Em vez de usar apenas pronomes demonstrativos como “this” e “that”, acrescente um substantivo que diga a que eles se referem
- “To solve this” é menos claro do que “To solve this shortage”
- “That will take you to the home screen” é menos claro do que “Successfully authenticating will take you to the home screen”
- O que parece repetição para quem escreve vira, para quem lê, uma clarificação que torna o texto mais fácil de acompanhar
Simplificar: tirar as palavras sem sentido
- O trabalho mais importante na edição é remover palavras que não contribuem para o significado
- “You will need to run this script” pode ser reduzido para “Run this script”
- “You can aid in readability by making sure…” pode ser reduzido para “Make sure…”
- Salvo motivo especial, o ideal é chegar ao ponto o mais rápido possível, sem enterrar o sentido em excesso de palavras ou estruturas ornamentais
-
Transforme instruções em imperativo
- Em instruções, “You should X” e “You can X” ficam mais concisos quando convertidos para o imperativo
- “You should save the file to your home directory” vira “Save the file to your home directory”
- Essa mudança reduz a contagem de palavras e leva o leitor diretamente à ação
-
Reduza estruturas com “of” e “for”
- Estruturas encadeadas com “of” ou “for” ficam mais eficientes quando reescritas para colocar a informação antes do substantivo principal
- “The manager of the team responsible for marketing” vira “The marketing team’s manager”
- Frases reorganizadas permitem que o leitor capte o sentido mais rapidamente, sem precisar reinterpretar cada trecho
-
Divida frases longas e use vírgulas
- Frases longas costumam funcionar melhor quando divididas em várias frases curtas
- No exemplo do projeto Acme, uma única frase incluía milestone, ambiente de servidor, melhoria no tempo de build e comparação com o plano XYZ; a versão revisada separa isso em três frases
- A versão revisada informa separadamente que os servidores non-staging rodam no ambiente Foobaz, que o build caiu para menos de 10 minutos e que no plano XYZ isso antes levava mais de 1 hora
- Adicionar vírgulas nos lugares certos ajuda o leitor a processar a primeira parte antes de seguir para o restante
- “If you’re looking for me, I’ll be in my office”
- “Due to the fog, our flight was delayed”
- Quando uma oração subordinada vem no início da frase, a vírgula é necessária e funciona como um ponto de processamento que ajuda na leitura
Reduza expressões que obscurecem o agente e o significado
-
Elimine a voz passiva
- A voz passiva esconde quem ou o que executa a ação
- Ao transformar uma construção passiva em voz ativa, a frase fica mais clara porque o leitor consegue ligar a ação à pessoa ou ao objeto corretos
- “The fire alarm was pulled and the building was evacuated” revela melhor os agentes como “The fire marshal pulled the alarm and the employees evacuated the building”
- “Millions of dollars were embezzled from the company” fica mais claro como “Two executives embezzled millions of dollars from the company”
- Em descrições de sistemas, escrever “An alert is triggered and the job is started” não mostra qual serviço dispara o alerta nem qual componente inicia o job
- Em documentação técnica, não explicitar o agente da ação reduz a precisão
-
Use verbos concretos e descrição em vez de advérbios
- Advérbios quase sempre podem ser substituídos por verbos mais específicos ou por uma descrição mais concreta
- Em “He laughed loudly”, “loudly” faz o leitor adivinhar o volume exato ou a sensação daquele riso
- Se a intenção real é dizer que “ele riu tão alto que o restaurante inteiro se virou para olhar”, é melhor descrever diretamente a situação
- Advérbios como “Basically” e “Essentially” muitas vezes funcionam como hedge; por isso, é melhor removê-los e dizer diretamente o que se quer dizer
Não presuma o conhecimento do leitor nem o tom
-
Explique siglas e conceitos
- Ao escrever sobre um tema muito familiar, é fácil esquecer o contexto que o leitor talvez não conheça
- Siglas e iniciais devem ser escritas por extenso na primeira aparição, com a abreviação entre parênteses, e depois disso pode-se usar só a sigla
- “TTFB” deve aparecer primeiro como “time to first byte (TTFB)”
- Acrescentar uma breve explicação quando um conceito aparece pela primeira vez ajuda o leitor a acompanhar melhor
- TTFB mede o tempo entre o momento em que o usuário envia uma requisição HTTP e o momento em que o navegador carrega o primeiro byte
- É usado como indicador de responsividade de um site
- Se necessário, pode-se fornecer um link para aprendizado adicional, como time to first byte (TTFB) metric
-
Consistência de tom
- O tom do texto, seja coloquial ou formal, deve ser definido e mantido de forma consistente
- Quando uma frase começa de forma muito coloquial e de repente muda para uma formulação acadêmica, isso pode confundir o leitor ou desviar sua atenção do conteúdo
- A frase de exemplo pode ser reescrita em tom consistente, como “No começo eu estava empolgado com o novo framework, mas não consegui capturar as métricas que queria”
Ajuste jargão, clichês e estrutura visual
-
Evite jargão e clichês
- No jargão de negócios aparecem expressões como “deep dive” e “low-hanging fruit”, e em outros textos também surgem clichês frequentes, como metáforas de beisebol
- O jargão presume que o leitor pertence ao grupo interno que usa essas expressões
- Para leitores que não são nativos em inglês ou não estão familiarizados com a cultura do beisebol, jargão e clichês podem dificultar o acompanhamento do texto
- “tl;dr, if you can hack something together by EOD…” contém siglas e gíria técnica, além de soar menos como um pedido
- “Can you deliver a prototype by the end of today?” vira um pedido claro ao perguntar diretamente pelo resultado esperado e pelo prazo
-
Use espaço em branco e formatação
- Espaço em branco é importante em documentação técnica e também funciona bem em posts de blog e e-mails
- Parágrafos longos são difíceis de ler, especialmente em telas, e podem fazer o leitor perder o foco
- Dividir visualmente a página facilita encontrar os pontos principais
- Quebre parágrafos longos em vários parágrafos curtos
- Crie estrutura com subtítulos úteis e permita que o leitor pule para as seções de interesse
- Organize itens relacionados em listas
- Ao transmitir muita informação, como em documentos de referência, tabelas podem ser melhores do que listas
- Use negrito para que leitores que estão só passando o olho consigam captar os pontos centrais
Filosofia de edição
- A filosofia de edição pode ser reduzida a dois pontos
- Não dependa de advérbios, jargão, clichês ou hedges; diga exatamente o que quer dizer
- Elimine todas as palavras desnecessárias
- Esses dois princípios servem como estrutura para revisar seus próprios textos e avaliar os de outras pessoas
- Com a prática, você desenvolve seu próprio estilo e suas preferências, e tudo bem se afastar de algumas recomendações desde que saiba por quê
- O objetivo da edição não é seguir regras sem senso crítico, mas usar a linguagem com consciência e fazer escolhas adequadas à mensagem que se quer transmitir
1 comentários
Comentários do Hacker News
Sou a pessoa que escreveu este texto. Fico feliz e honrada por ele ter tocado tantas pessoas. Depois de escrevê-lo, segui minha curiosidade e me tornei engenheira de software; após alguns anos trabalhando, senti falta de funções com uma parcela maior de escrita Se alguém souber de vagas para excelente redatora técnica, developer advocate ou funções que misturem especialização em comunicação com capacidade técnica, por favor me avise. Dá para entrar em contato pelo formulário do site(https://evaparish.com/contact) ou pelo LinkedIn
Uma das coisas que mais me incomodam ao ler documentação técnica é quando aparece uma sigla que ainda não foi apresentada ao leitor. Isso se repete em vários pontos da documentação de um projeto e, quando os responsáveis mudam ao longo dos anos, chega-se a situações em que ninguém mais sabe do que certa sigla significa Na prática, já vi várias vezes a situação estranha em que uma equipe desenvolve e mantém um serviço chamado ABC, mas nenhum integrante sabe do que ABC é sigla. Nesses casos, para evitar o trabalho de escolher um nome novo e atualizar toda a documentação relacionada, acaba-se tratando ABC como se fosse um nome próprio e segue-se em frente Exemplo fictício: para obter um token de acesso para o CDIS, vá até o DMC de e clique no item "CDIS" na barra lateral esquerda, depois pressione "Generate Access Token" para copiar o token Eu preferiria ler assim: para obter um token de acesso para o Customer Data Indexing Service (CDIS), vá até o Data Management Console (DMC) de e clique no item "CDIS" na barra lateral esquerda, depois pressione "Generate Access Token" para copiar o token