O que é redação técnica e um pouco do que aprendi nesses meses

Como tem sido minha experiência como technical writer e meus aprendizados escrevendo documentações técnicas de soluções open source

Desde que me tornei technical writer, ou redatora técnica, tenho tido a oportunidade de desbravar um mundo completamente fora da minha realidade como jornalista: o da tecnologia.

E aqui, quando me refiro à tecnologia, quero dizer todo o ecossistema envolvido nela, desde o ciclo de vida de um software, os bastidores do desenvolvimento de uma solução e, principalmente, o desafio de criar uma documentação intuitiva, que oriente futuros usuários a utilizar aquele produto e entender seus atributos e features técnicos.

Por isso, decidi compartilhar um pouco da minha trajetória até aqui como forma de, quem sabe, incentivar potenciais comunicadores a se desbravarem nesse mundo - além, é claro, de fortalecer essa comunidade ainda em crescimento no Brasil.

Antes de tudo, quero deixar claro que a redação técnica não se restringe à área da tecnologia. Isso significa que existem technical writers, por exemplo, na Medicina e em áreas que exijam conteúdos com estilo técnico mais aprofundado. Mas, para este artigo, vou focar todos os meus exemplos na área tech por ser nela que atuo.

Mas afinal, o que é technical writing?

De acordo com a Society for Technical Communication, o Technical Writing é um campo, dentro da comunicação técnica, que possui pelo menos uma das seguintes características:

Usar a comunicação para abordar assuntos técnicos e especializados, como aplicações (ou apps) e softwares, entre outras ferramentas que possam ser instaladas, adicionadas ou configuradas;
Utilizar de meios tecnológicos, como sites, repositórios, arquivos ou redes sociais para comunicar sobre o produto;
Prover instruções sobre como realizar algo, independentemente do quão técnica seja a ação ou de qual tecnologia seja necessária para realizar a tarefa.

Em outras palavras, a redação técnica é quando escrevemos de forma clara e intuitiva sobre instruções ou orientações para que o(a) leitor(a) possa entender mais facilmente como usar uma solução/software/produto.

As entregáveis do technical writer

Considerando que nosso principal objetivo é tornar mais fácil o uso de alguma solução e/ou produto, os principais materiais que um redator técnico produz são:

Documentações técnicas de softwares, incluindo documentações de API;
Manuais de instrução;
Guias de uso.

Arrisco dizer que o principal deles é a documentação.

No universo de technical writing, ela (a doc) é o elo entre quem usa e quem produz um software ou sistema. A “interface” que pode potencializar a experiência em usar aquela solução.

E, por isso, é fundamental que a documentação (ou doc, como costumamos chamar) seja bem escrita, com exemplos de uso e explicações conceituais e técnicas para facilitar o entendimento de como usar o produto.

Como me tornei redatora técnica?

Assim como boa parte dos redatores técnicos que conheço, eu entrei na área por acaso.

No início deste ano, quando a pandemia estava nem perto de ser realidade, eu recebi uma proposta da Zup Innovation. Na época, tudo indicava que eu teria uma atuação bem parecida com a que vinha fazendo, no caso, a de UX Writer ou Redatora UX.

O que sabia, até então, é que eu precisaria ser bastante organizada e ter experiência prévia em documentar processos.

Porém, quando eu comecei a trabalhar, já nos primeiros dias entendi que estava lidando com algo totalmente novo. O desafio era - e continua sendo - escrever as documentações das soluções open source que a Zup vem lançando na comunidade de desenvolvedores.

Isso significa que eu precisei entender a fundo sobre termos e expressões de programação, além de conhecer, tecnicamente, como o produto funcionava para que eu pudesse explicá-lo na documentação. Aliás, tive que entender sobre três produtos que envolvem três áreas distintas - ainda que correlatas - dentro de tecnologia.

Para completar, as equipes dos produtos para os quais eu escrevo ficam em Uberlândia (MG), enquanto eu moro em São Paulo (SP). E aí vocês devem imaginar como o desafio aumentou, certo?

Inclusive, se vocês quiserem, eu posso escrever outro artigo só contando estes bastidores. Mas o que posso adiantar aqui é que foram meses de bastante aprendizado enquanto - literalmente - ia escrevendo cada linha dessas docs. 😉

Alguns dos aprendizados que tive (até agora)

Como disse, essa trajetória tem me feito colher muitos frutos e aprender sobre processos de trabalho e assuntos da área de tecnologia que nem sonhava em me envolver.

Abaixo, listo o que já aprendi e que pode ajudar caso você, um dia, decida trabalhar com redação técnica:

1. Pense como um desenvolvedor

Se você, como eu, estiver trabalhando em uma empresa de tecnologia, é bem provável que seu público-alvo seja formado por desenvolvedores, arquitetos ou engenheiros de software.

Logo, é interessante que você mergulhe no universo desses profissionais para entender como eles consomem informações técnicas e quais seus formatos favoritos de conteúdo.

Isso significa pesquisar e aprender sobre temas comuns à área, como APIs, Git, Github, Gitlab, infraestrutura, tipos de ambientes, linguagens de programação e linhas de comando, entre outros.

Existem vários cursos online da Udemy que tratam destes temas. Eu, por exemplo, comecei a fazer recentemente um chamado Git and Github for Writers. Mas você pode encontrar outros que lhe interessem e façam mais sentido para seu atual momento. 🙂

2. Escreva perto de quem desenvolve o produto

Não existe uma boa documentação, seja ela escrita ou codificada, sem um trabalho multidisciplinar por trás.

Por mais que você, enquanto redator técnico, compreenda o universo do produto, faz toda diferença quando você traz desenvolvedores, analistas de QA e demais envolvidos no desenvolvimento do software/solução para contribuir.

Desta forma, a documentação se enriquece com estudos de caso, exemplos de códigos e demais informações técnicas que irão agregar na experiência de leitura do arquivo.

No começo, ainda mais se a empresa não tiver uma equipe de tech writers, é normal que os times de produto se mostrem um pouco resistentes. Mas use as skills de comunicação em seu favor e garanto que o resultado será melhor do que você espera. 😉

3. English first

Talvez este seja meio óbvio, mas não custa reforçar: todo o universo de tecnologia, inclusive de softwares e soluções, compartilha conteúdos dando preferência ao inglês.

Caso você trabalhe, queira trabalhar ou vá começar em uma empresa que pretende ampliar o alcance de seu produto, então minha recomendação é que você invista no inglês para ganhar segurança em tradução e na escrita da documentação, principalmente.

4. Concilie usabilidade e conhecimento técnico

Este foi um de meus maiores desafios. Como não sou desenvolvedora, minha vivência sempre me coloca em uma posição de questionar o quão intuitivo e claro está o conteúdo. Ao mesmo tempo, não posso deixar de tratar tecnicamente do assunto.

No dia a dia, é como uma balança em que precisamos avaliar o tempo todo como está esse equilíbrio. Por um lado, não podemos ser didáticos demais a ponto de esquecer do técnico. Por outro, também não podemos ser técnicos demais. O segredo, então, é ser claro naquilo que se está dizendo.

Não existe fórmula mágica: é necessário sempre validar, revisar e testar a documentação com sua audiência.

5. A doc é um documento vivo

Mesmo que você finalize o processo de documentação, ele nunca irá acabar. Isso porque vira e mexe surge uma nova atualização no software e você precisa divulgá-la por meio das chamadas release notes.

No caso de soluções open source, então, é sempre importante que o redator técnico acompanhe as contribuições que a solução vai receber via repositório, além das necessárias revisões ou inclusões de features à medida que o produto estiver evoluindo.

Onde encontro mais informações?

Como falei no início deste artigo, a área de technical writing no Brasil ainda está crescendo e existem muitas oportunidades para profissionais interessados em fazer carreira nela.

Se quiser saber mais, vou deixar abaixo recomendações de livros e também links para dois grupos (um brasileiro e outro estrangeiro) que vai colocar você em contato com outras pessoas que já trabalham como tech writers.

Livros

Grupos

Technical Writing Brasil, no Linkedin.
Write The Docs, no Slack.

Extra: Poscast

Eu não podia deixar de divulgar o The Manu<script>, podcast criado pelos technical writers Breno Barreto e Juliana Meyer, ambos da VTEX.

Ele está disponível nos principais tocadores e cada episódio é uma verdadeira aula sobre os desafios da área e percepções do mercado - inclusive, com a participação especial de alguns dos autores dos livros que listei acima.

Espero que vocês tenham entendido um pouco desse universo complexo e apaixonante do Technical Writing. Pretendo escrever mais artigos em breve, então, se quiserem, podem ficar à vontade para enviar sugestões de temas relacionados. Será um prazer falar sobre eles. 😊