Comunicação escrita para devs

Comunicação escrita é uma das competências mais utilizadas e ao mesmo tempo subestimadas por desenvolvedores. E não é como se fosse algo muito difícil de se melhorar. Um esforço consciente e recorrente em escrever melhor pode ajudar qualquer pessoa a ter mais clareza, efetividade e empatia em sua comunicação escrita. Escrever muito bem consistentemente pode ser difícil, mas não escrever mal consistentemente é fácil — apenas trabalhoso.

Escrever melhor ajuda tanto a melhorar seu código diretamente, com bons nomes de variáveis e métodos, boas descrições de testes, boas mensagens de commit e descrições de PR; quanto a aumentar indiretamente o valor que o seu código entrega, através de emails mais claros e diretos, documentação mais compreensível, debates técnicos e não técnicos mais produtivos, apresentações melhores.

Quem se importa?

O primeiro passo é se importar. Se você envia um email sem revisar para melhorar a maneira como escreveu, é um sinal que você não se importa. Como ninguém faz code review do seu email, ele acaba sendo enviado com bugs, problemas de performance, dificuldade de leitura; exatamente como um código.

Importar-se com sua escrita significar fazer um esforço consciente em melhorá-la. Não é difícil fazer com que as palavras sejam ferramentas que lhe ajudam em seu trabalho e não empecilhos no seu caminho.

As razões explícitas e implícitas para um profissional não se importar com sua escrita são, ao mesmo tempo, causa e justificativa para seus problemas de comunicação. “Não se importar” vem em dois modos: negligência consciente e inconsciente.

A negligência consciente geralmente vem acompanhada de arrogância. Como se ter o trabalho de escolher melhor as palavras para explicar um conceito estivesse abaixo de você. Como se o seu código fosse o suficiente para falar por si só e nada do que você escrevesse fora do seu editor de código importasse. Mas acredito que pessoas que conscientemente não se importam com sua escrita nem estão lendo isso; então não vou me alongar muito nesse caso.

Agora, negligenciar inconscientemente sua escrita é a maneira mais comum de fazê-lo. Você tem a ideia em sua cabeça, escreve no modo automático, mal processando aquilo que vem do seu cérebro e então termina de escrever sua ideia, considera o trabalho feito e vai para a próxima tarefa. Você assume que a sua ideia está refletida naquelas palavras já que, obviamente, você escreveu aquelas palavras para expressar sua ideia. O que poderia dar errado? Muita coisa.

Mais que uma ideia

A mensagem que você escreve engloba muito mais que a ideia principal que você quer transmitir. O que você está negligenciando inconscientemente é tudo o que você tem em sua cabeça ao escrever sua mensagem que seus leitores não tem ao lê-la. Coisas como: premissas que fundamentam sua ideia, o contexto no qual aquela ideia é aplicada, o significado exato que você está usando em palavras ambíguas, a conclusão que você quer chegar naquele texto, o acesso a outros textos que ajudam a definir sua ideia, a certeza do tom e intenção que aquelas palavras deveriam refletir.

Tudo isso é o tipo de coisa que você raramente nota na sua própria escrita, mas que vai atrapalhar o leitor desde o primeiro momento. A boa notícia é que não é difícil evitar esses lapsos seguindo um processo simples:

Pense em qual mensagem quer transmitir antes de escrevê-la.

Pense na pessoa que está lendo enquanto escreve.

Reescreva.

Antes de escrever: pense na mensagem

É importante ter bem clara em sua mente a mensagem que você quer transmitir. Ajuda muito listar num rascunho todas as informações que você quer incluir na mensagem, ordenando por importância do tópico. Geralmente existe uma mensagem principal que lhe leva a escrever, que deve estar clara para qualquer um que leia o texto. Deixar explícito para você mesmo qual é essa mensagem essencial é condição necessária para que você sequer escreva a primeira palavra.

Essa mensagem não precisa conter apenas fatos, como uma nova funcionalidade que está no ar; ou opiniões suas, como sua posição na escolha da linguagem de um novo projeto. Às vezes a mensagem principal que você quer transmitir pode ser algo intangível. Por exemplo: transmitir senso de urgência para uma tarefa.

Mensagens secundárias

Agora, se você quer transmitir um senso de urgência, ao mesmo tempo também deve querer tomar cuidado para ser educado e não parecer autoritário.

Transmitir conceitos abstratos pode ser complicado e quando envolve muita subjetividade, como sentimentos e percepções, é um desafio cheio de perigos. O perigo de ser sutil demais, o perigo de ser agressivo, de ser passivo-agressivo, o perigo de parecer grosso, arrogante, pretensioso. Por isso é sempre bom fazer uma auto-checagem se suas intenções são sinceras e transparentes. Mas com comunicação escrita, ter boas intenções é raramente suficiente.

Se você faz essa checagem e tem claro que sua mensagem é apenas transmitir um senso de urgência para uma tarefa de outro time — e não é simplesmente reclamar, cobrar ou se intrometer, então você pode ser transparente e explícita em suas intenções. Seu texto pode ser algo como: “Em relação àquela tarefa, gostaria de avisar que ela é de bastante urgência para mim por causa do seu impacto em outra tarefa que eu tenho com meu time. Eu não quero me intrometer no seu processo de trabalho ou parecer que estou cobrando, apenas informando para ficarmos alinhados na necessidade da tarefa. Obrigado!”

Os termos são bem genéricos, pois é um exemplo hipotético, mas uma versão melhor ainda seria se dar ao trabalho de explicar como uma tarefa afeta a outra. Isso sinalizaria que você quer convencer o leitor que a urgência é real, e não apenas informá-lo do fato. Nesse exemplo texto também foi possível perceber um exercício de empatia, de perceber como o texto poderia ser entendido e antecipar possíveis mal-entendidos.

Mas é importante notar uma coisa sobre esse exemplo: ele certamente está errado no tom usado. Pode estar muito formal, muito informal, muito curto, muito longo, depende do contexto. É impossível encontrar o tom correto do texto se o leitor é imaginário. Se quando você leu a mensagem ela lhe pareceu um pouco estranha, um bom exercício é reescrevê-la de um modo que você se sentiria confortável ao lê-la. Escrever pensando no leitor, não como uma entidade abstrata, mas sim como a pessoa real que vai ler seu texto, é essencial em qualquer situação.

Enquanto escreve: pense em quem está lendo

Como escritor, você está a serviço do leitor. Como não estamos falando de escrita literária, você deve evitar qualquer ambiguidade e priorizar conteúdo sobre estilo. A pessoa que vai ler seu texto é o ditador de cada palavra que você escreve. Você deve escolher o sinônimo que o leitor mais provavelmente irá reconhecer, você deve saber com quais conceitos o leitor é mais ou menos familiarizado, você deve saber onde e quando o leitor vai ler seu texto. Você tem que exercitar sua empatia, antecipando possíveis dúvidas, causas de confusões e contra-argumentos. Enquanto escreve, você deve pensar como seu leitor.

Um grande começo, para toda comunicação, é estabelecer o conhecimento em comum, garantir que você e o leitor estão na mesma página. Isso é na prática muito fácil, basta dizer explicitamente sobre o que você está falando naquele texto logo no começo. Isso é primordial em emails. A primeira coisa que você escreve é sobre o que é aquele email. Um anúncio de nova funcionalidade, uma reclamação, um informativo, um pedido. Uma linha bastante objetiva para dar contexto.

Isso é particularmente importante em canais de comunicação que não fornecem o contexto por eles mesmos, como emails e mensagens no Slack. Em emails, é uma boa prática inclusive repetir a frase de contexto no assunto e na primeira linha do corpo do email. No Slack, já inclua o contexto na mesma linha em que dá o “Oi” inicial. Em comparação, a descrição de um Pull Request já herda muito do contexto de coisas como o repositório, a branch, as labels, ou mesmo o próprio meio, que diz que você está adicionando algo novo a uma base de código. Assim já é possível começar a descrição com qual a mudança ou o motivo da mudança.

Escrevendo para o futuro

Não por acaso a funcionalidade de criar PR no Github dá tanta ênfase em contexto. Alguns de seus leitores estão no futuro. Seja o seu eu futuro ou futuros desenvolvedores que sua empresa nem contratou ainda e nunca irão lhe conhecer. Então todo o contexto que você tem inerentemente só por viver no presente precisa ser explicitamente registrado.

Muito da escrita que está em conexão mais direta com o código tem como preocupação principal essa comunicação com o futuro. Então quando estiver escrevendo coisas como mensagens de commit, entenda que pensar no leitor é pensar em alguém que vive no futuro e pode não ter o contexto e conhecimento de muita coisa que é trivial para você hoje.

Escrevendo para pessoas diferentes de você

Outro tipo de desafio é comunicar tópicos técnicos para pessoas não-técnicas. É uma linha muito tênue entre ser didático e ser condescendente, entre explicar usando analogias e nivelar por baixo a explicação, entre usar termos tecnicamente corretos e ofuscar o conceito principal.

Uma boa prática é decidir de antemão quais termos e conceitos você quer e quais não quer explicar. Você pode decidir que é importante explicar o que é um “deploy”, pois é um termo muito comum, frequente e que afeta o trabalho de outras pessoas não técnicas que estão esperando uma funcionalidade. Mas optar por não entrar no detalhe de explicar que você está esperando “code reviews no seu PR para poder mergear”.

Se você acha que vai ser útil para o leitor aprender sobre um determinado tópico, inclua uma explicação adequada sobre ele no seu texto. Assim você compartilha o conhecimento e possivelmente economiza seu tempo no futuro quando voltar a se comunicar com a mesma pessoa. É saudável utilizar termos e conceitos que são um pouco — mas apenas um pouco — mais avançados do que você espera que o leitor conheça. Desse modo, se você subestimou o conhecimento do leitor, você tem uma margem de segurança e evita parecer condescendente. Já se você superestimou o conhecimento, só é necessário explicar um pouco mais sobre o tema. Na média, você acaba expandindo o conhecimento do leitor sem aliená-lo.

Após escrever: releia pensando na mensagem, na pessoa e reescreva.

Se o texto é importante, uma boa heurística é considerar um texto completo apenas quando você o relê de ponta a ponta e não encontra uma vírgula sequer que queira mudar. Uma versão da regra um pouco menos rígida, para textos não tão importantes, é considerar um texto completo uma vez que você não faz nenhum alteração de sentido ao reler.

De qualquer modo, este pequeno algoritmo requer ao menos uma releitura completa após você ter terminado de escrever a primeira versão. Mas antes de entrar mais a fundo no tema da reescrita, lembre-se que para reescrever, você precisa escrever primeiro. Não subestime esse primeiro passo.

Jogando um quebra-cabeça na mesa

Não importa o quanto você pensou de antemão sobre sua mensagem, o quão empático com o seu leitor você quer ser, o foco da primeira versão deve ser apenas colocar sua ideia no papel. Você tem muita coisa na cabeça e você tem que despejar todo esse conteúdo antes de poder se dedicar a aprimorá-lo.

Escrever é como montar um quebra-cabeça. A ideia na sua cabeça é a linda imagem na caixa do quebra-cabeça. O seu primeiro rascunho é o momento em que você abre a caixa e joga todos as peças na mesa. É então que começa o trabalho de transformar a bagunça da mesa na imagem que você tem na sua cabeça.

Os fundamentos se mantém os mesmos nesse processo de releitura e reescrita: pensar na mensagem e na pessoa que vai ler. Você descobre todo tipo de coisa ao reler seu texto. Um conceito técnico não está claro. Parte da mensagem está faltando. O tom não é o adequado de acordo com suas próprias intenções. Um parágrafo não é coerente por si só. Existem palavras que o leitor provavelmente não vai entender. Um sinônimo escolhido não aquele exato significado que você queria transmitir. Existem palavras repetidas. Faltam palavras. Tem muitas palavras. Typos. Erros gramaticais e ortográficos. Uma frase está muito longa e difícil de entender. A formatação está atrapalhando o entendimento. Uma palavra ou frase está ambígua. Tudo isso são bugs no seu texto impedindo ele de cumprir seu papel e transmitir a mensagem correta.

Parece que não, mas importa

Algumas coisas são de particular importância na releitura e costumam passar despercebidas.

Formatação — deixe o leitor escolher o que quer ler

Como você usa negrito, itálico, bullet points, subtítulos e quebra de linhas importam muito para o entendimento da mensagem.

Sempre pule uma linha a mais entre parágrafos em emails, descrições de PR, etc. Um parágrafo deve encapsular um conceito único, mantendo coerência e completude em si mesmo. Então é importante para o leitor notar visualmente essa separação de tópicos.

Use negrito e itálico, mas não abuse. Negrito é muito útil em evidenciar qual o foco de uma frase, mas se tudo é foco, nada é foco. Deixe citações visualmente óbvias usando de maneira redundante aspas e itálico. Se disponível, aprenda a usar todos os recursos de estilos markdown: trechos de código, listas ordenadas e não ordenadas, títulos e subtítulos.

Formatação é essencial para a leitura daqueles estão apenas passando os olhos pelo seu texto. É importante dar a opção para o leitor ler seu texto do modo que ele preferir e você só dá essa opção se formatou adequadamente seu texto.

Ordenação — sem suspense, sem pressa

A ordem que você apresenta as informações no seu texto é fundamental. Uma regra é: nunca crie suspense para a sua mensagem principal. A regra de fornecer o contexto em uma frase logo no começo do email é um exemplo disso. É fácil se iludir e achar que você vai conseguir criar uma atmosfera e aumentar o interesse do leitor antes de soltar a informação que vai impressionar todo mundo. O mais provável é que você vá irritar boa parte dos leitores e muitos vão desistir de ler antes mesmo de chegar na mensagem principal. Mesmo que você tenha o talento para criar textos literários de suspense, comunicação profissional não é o local para criar um roteiro de Black Mirror com plot twist e finais ambíguos.

Por outro lado, se a mensagem que você quer transmitir é completamente nova para os leitores, ao tentar ir direto ao ponto, você corre o risco de ir muito rápido e confundir todo mundo. Nesse caso, é melhor aplicar outra regra: comece do mais familiar e vá evoluindo gradativamente para a novidade.

Comece com ideias que o leitor já conhece e mostre como elas evoluem para as novas ideias que você quer apresentar. Ideias familiares podem ser tanto por conhecimento prévio que você assume que o leitor tenha ou por ideias que você tenha acabado de apresentar no parágrafo anterior. Essa regra de sempre ir do mais familiar para o mais novo se aplica em todos os níveis do seu texto: a ordenação dos parágrafos no seu texto, das frases no parágrafo, das palavras na frase. É uma maneira incrivelmente prática de criar ritmo e fluidez no seu texto.

O desafio é balancear essas duas diretrizes: não criar suspense, nem apressar muito seu texto. Um caminho é citar o conceito novo logo de cara, mas de uma maneira muito objetiva e curta e já na mesma frase deixar claro que irá explicar melhor o que quer dizer ao longo do texto.

Escolha de palavras — sinônimos ainda são palavras diferentes

Não existem duas palavras diferentes que tenham um significado exatamente igual em todas as suas dimensões, em todos os seus contextos. A linguagem é mais orgânica e menos lógica que código. Cada escolha de palavra traz juntos uma série de nuances em seu significado. Mesmo o significado de uma mesma palavra varia através do espaço e do tempo.

Sempre procure a palavra mais familiar para você e para o leitor. Qualquer ousadia traz riscos à efetividade da comunicação. Você pode decidir arcar com esses riscos, mas esteja ciente deles. Adapte o termo ao contexto também: não seja muito formal para a ocasião, nem muito informal, nem muito esnobe, nem muito vulgar. Você quer que o leitor entenda a sua mensagem sem ser distraído pelo seu vocabulário.

Mas todas essas recomendações estão sujeitas a uma regra fundamental: nunca sacrifique o significado da sua mensagem. Se você já tem a palavra ideal que reflete o conceito exato que deseja passar, não troque. Mesmo que seja uma palavra muito formal para a ocasião ou pouco familiar para o leitor. Se necessário, inclua mais contexto e explicações para que a palavra não confunda a cabeça do leitor. Cada palavra conta, escolha com cuidado.

Estrutura de frase — voz ativa com exceções

Como regra padrão, use a voz ativa nas suas frases — quando um “sujeito faz alguma coisa”, ao invés de “algo foi feito pelo sujeito”. É mais fácil para o leitor compreender e traz mais objetividade no modo que você transmite sua mensagem.

Mas existem algumas exceções importantes a essa regra. Quando você está seguindo o princípio de ordenar sua frase do mais familiar para o menos familiar, pode acontecer que a informação mais familiar não seja o sujeito da frase. Veja o exemplo dessas duas frases:

“Eu não queria usar essa linguagem para esse projeto. Essa decisão foi tomada pelo nosso CTO”.

A segunda frase fica mais clara quando você a inicia com uma referência à decisão explicada na primeira frase. Fica uma transição mais suave entre uma frase e outra.

Outra exceção é quando você não tem a intenção de dar importância para o sujeito da frase. Por exemplo:

“O nosso time é o Squad Go Horse e trabalhamos junto ao time de Marketing, mas só atualizamos as landing pages do site. Já as páginas institucionais são atualizadas por outro squad.”

A segunda frase está na voz passiva porque o foco da mensagem é apresentar o que é parte do escopo do seu time e o que não é, sem entrar no detalhe de quem é o outro squad que cuida das páginas institucionais.

E a voz passiva acaba sendo a única opção se você não quer ser explícito sobre quem e o sujeito da frase. Por exemplo:

“A decisão de usar Cobol foi tomada, agora temos que lidar com isso.”

Essa frase é adequada se a tal decisão é polêmica e você não quer entrar no mérito sobre quem tomou a decisão e suas razões, quer apenas transmitir o senso que não há nada a ser feito e todos devem ser pragmáticos sobre o assunto. Se reescrevermos essa frase incluindo o sujeito, a intenção da frase se transforma completamente:

“O CTO tomou a decisão de usar Cobol, agora temos que lidar com isso.”

A impressão do leitor é que o CTO é o foco da mensagem, implicando que você está criticando sua decisão e que você está lidando com suas consequências com mais rancor que pragmatismo.

Sua comunicação funcionou?

É fácil praticar uma escrita mais profissional e efetiva. Mas como saber se você está melhorando? Sem receber de volta uma sinalização se suas ações tiveram o efeito desejado ou não fica difícil aprender. O feedback sobre a efetividade da comunicação é sutil e escondido. Aprenda a reconhecê-lo.

Comunicação escrita é normalmente assíncrona e raramente você recebe feedback espontâneo sobre suas habilidades de comunicação. Outro complicador é que a mensagem que você quer passar é sempre mais importante do que como você a passa. Então você tem que buscar ativamente feedback sobre sua comunicação e destilar os comentários que são de fato feedback sobre sua habilidade em comunicar.

O caso mais óbvio é quando pessoas criticam o tom de sua escrita. Se pessoas falam que você pareceu grosso, exigente ou seco em seu email — e você não tinha a intenção de ser nada disso — então isso é um feedback sobre sua escrita. Mas em outras situações onde as pessoas se irritam é mais difícil ter feedback. Se você é muito prolixo, faz muitas piadas ou usa muitos emoticons nos seus emails, é mais difícil ter seus leitores espontaneamente lhe dizendo isso. Por isso é importante ir pedir a opinião de pessoas com confiança suficiente para serem honestas.

Agora, uma ocasião onde pedir feedback não ajuda muito é uma das mais importantes: se sua mensagem foi entendida. As pessoas só podem responder baseado no que entenderam, e se elas entenderam errado, elas ainda assim podem dizer que entenderam perfeitamente. Como descobrir se elas entenderam certo então? Você sempre tem pistas no que as pessoas falam para você na continuação da conversa.

Quando alguém lhe pergunta algo que você já havia dito em um email anterior, não é um vacilo do lado deles, é um feedback sobre sua comunicação. É descortês dizer “Como já havia dito anteriormente…” e repetir a mesma coisa que disse antes. Aproveite a oportunidade para reler o que você escreveu da primeira vez e mudar para melhorar a clareza. Quando fica evidente que alguém não leu até o final o que você havia escrito, a ordem do texto poderia ter sido melhor, ou o texto estava muito longo, ou a leitura era muito difícil.

Claro, todos esses mal-entendidos por parte dos leitores pode ser culpa exclusivamente deles, e não sua. Comunicação sempre tem dois lados e basta apenas um deles para arruinar tudo. Mas é mais produtivo assumir que a falha é do seu lado. Você falhou de comunicar adequadamente algo e abriu uma brecha para que o outro lado o interpretasse errado. Isso não precisa ser verdadeiro para ser útil.

Você pode praticar uma escrita defensiva, tentando evitar todas as maneiras que o leitor pode interpretar errado o seu texto. Você tem apenas que assumir boa fé por parte do leitor em querer entender certo. Se este não é o caso, você precisa de uma escrita extremamente defensiva que é a especialidade de advogados. E a linguagem do juridiquês é o oposto de comunicação efetiva em ambientes profissionais em geral. Então, se você tem um chefe ou colega que está sempre propositalmente interpretando mal o que você escreve, você tem um problema maior em mãos do que suas habilidades de escrita.

Pratique sua escrita de maneira consciente, sempre reescreva seus textos para melhorá-los, fique atento ao feedback sutil sobre a efetividade de sua comunicação. Sua vida de desenvolvedor vai ficar bem mais fácil.

Para quem tiver interesse em ler mais sobre comunicação escrita, estou pensando em começar uma newsletter.

Não tenho certeza ainda se vou assumir esse compromisso, depende um pouco de quantas pessoas se interessarem. Então se gostou da ideia, ponha seu email na lista: https://escritaparadevs.substack.com

Tem interesse em trabalhar conosco? Nós estamos sempre procurando por pessoas apaixonadas por tecnologia para fazer parte da nossa tripulação! Você pode conferir nossas vagas aqui.